> For the complete documentation index, see [llms.txt](https://docs.telm.ai/telmai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telm.ai/telmai/api-reference/authentication-api/api-keys.md).

# API Keys

An alternate way to access Telmai APIs using API Key.

All Telmai APIs can be executed either with an OAuth access token or an API key. Use the APIs below to create a key, then send it in the header of any Telmai API instead of the `Authorization` bearer token:

```http
X-TLM-Key:{API Key}
```

Execute the Authenticate API to retrieve the access token used in the `Authorization` header for the calls below.

## Key scope

API keys are **user-scoped**: a key belongs to the user who created it, and it carries that user's access. Any user can create a key for themselves — this is no longer restricted to tenant administrators.

The endpoints below take no tenant path parameter. The key's owner and tenant are resolved from the credentials used to call them.

{% hint style="info" %}
Keys issued before v26.3.4 continue to work unchanged.
{% endhint %}

{% hint style="warning" %}
When a user is deactivated, any API key belonging to that user is disabled.
{% endhint %}

API keys are managed through the API only — there is no UI for creating or revoking them.

***

## Create an API Key

Creates an API key for the current user. The key value is returned **only** in this response — store it securely, as it cannot be retrieved again.

<mark style="color:green;">`POST`</mark> `{auth_endpoint}/auth/api_keys`

#### Request Body

| Name                                     | Type   | Description         |
| ---------------------------------------- | ------ | ------------------- |
| `name`<mark style="color:red;">\*</mark> | string | Name of the API Key |

{% tabs %}
{% tab title="curl" %}

```bash
curl -X 'POST' \
  '{auth_endpoint}/auth/api_keys' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<name>"
}'
```

{% endtab %}
{% endtabs %}

**Responses**

{% tabs %}
{% tab title="200" %}

```json
{
  "id": "string",
  "name": "string",
  "key": "string"
}
```

{% endtab %}

{% tab title="401" %}
`Unauthorized`
{% endtab %}

{% tab title="403" %}
`Forbidden`
{% endtab %}

{% tab title="404" %}
`Not Found`
{% endtab %}
{% endtabs %}

## Retrieve all API Keys

Returns the API keys belonging to the current user. Key values are not included.

<mark style="color:blue;">`GET`</mark> `{auth_endpoint}/auth/api_keys`

{% tabs %}
{% tab title="curl" %}

```bash
curl -X 'GET' \
  '{auth_endpoint}/auth/api_keys' \
  -H 'accept: */*'
```

{% endtab %}
{% endtabs %}

**Responses**

{% tabs %}
{% tab title="200" %}

```json
{
  "keys": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
`Unauthorized`
{% endtab %}

{% tab title="403" %}
`Forbidden`
{% endtab %}

{% tab title="404" %}
`Not Found`
{% endtab %}
{% endtabs %}

## Get details of a specific API Key

Fetches one of the current user's API keys by its unique key ID.

<mark style="color:blue;">`GET`</mark> `{auth_endpoint}/auth/api_keys/{keyId}`

#### Path Parameters

| Name                                      | Type   | Description       |
| ----------------------------------------- | ------ | ----------------- |
| `keyId`<mark style="color:red;">\*</mark> | string | Unique API Key ID |

{% tabs %}
{% tab title="curl" %}

```bash
curl -X 'GET' \
  '{auth_endpoint}/auth/api_keys/<keyId>' \
  -H 'accept: */*'
```

{% endtab %}
{% endtabs %}

**Responses**

{% tabs %}
{% tab title="200" %}

```json
{
  "id": "string",
  "name": "string"
}
```

{% endtab %}

{% tab title="401" %}
`Unauthorized`
{% endtab %}

{% tab title="403" %}
`Forbidden`
{% endtab %}

{% tab title="404" %}
`Not Found`
{% endtab %}
{% endtabs %}

## Delete an API Key

Removes one of the current user's API keys.

<mark style="color:red;">`DELETE`</mark> `{auth_endpoint}/auth/api_keys/{keyId}`

#### Path Parameters

| Name                                      | Type   | Description                                     |
| ----------------------------------------- | ------ | ----------------------------------------------- |
| `keyId`<mark style="color:red;">\*</mark> | string | The unique identifier of the API Key to delete. |

{% tabs %}
{% tab title="curl" %}

```bash
curl -X 'DELETE' \
  '{auth_endpoint}/auth/api_keys/<keyId>' \
  -H 'accept: */*'
```

{% endtab %}
{% endtabs %}

**Responses**

{% tabs %}
{% tab title="200" %}

```json
{
  "message": "API key was deleted successfully"
}
```

{% endtab %}

{% tab title="401" %}
`Unauthorized`
{% endtab %}

{% tab title="403" %}
`Forbidden`
{% endtab %}

{% tab title="404" %}
`Not Found`
{% endtab %}
{% endtabs %}

***

## Tenant-scoped endpoints (deprecated)

{% hint style="warning" %}
The tenant-scoped endpoints below are **deprecated and scheduled for removal**. Use the user-scoped endpoints above instead.
{% endhint %}

These endpoints remain available to tenant administrators, and are how an administrator lists or revokes keys across an entire tenant rather than only their own.

| Operation            | Endpoint                                                                                 |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Create a key         | <mark style="color:green;">`POST`</mark> `{auth_endpoint}/auth/{tenant}/apiKeys`         |
| List all tenant keys | <mark style="color:blue;">`GET`</mark> `{auth_endpoint}/auth/{tenant}/apiKeys`           |
| Get one key          | <mark style="color:blue;">`GET`</mark> `{auth_endpoint}/auth/{tenant}/apiKeys/{keyId}`   |
| Delete a key         | <mark style="color:red;">`DELETE`</mark> `{auth_endpoint}/auth/{tenant}/apiKeys/{keyId}` |

Request bodies and response shapes are identical to the user-scoped endpoints. `tenant` is the tenant identifier, which can be retrieved from the URL.