> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keys

> Keys the gateway issues to agents and teams, presented on every request.

A key is a credential for one instance's API. The gateway issues a key to an agent or a team, and the agent presents it on every request. Telnyx holds the instance's master key and never shows it.

## Issuance

Send [`POST /v2/agent_gateways/{id}/keys`](https://developers.telnyx.com/api-reference/agent-gateway-keys/create-a-key). Every field is optional, and a key's `name` is unique on the instance. A key with a `team_id` belongs to that [team](https://developers.telnyx.com/docs/agent-gateway/authorization/allow-lists.md#teams) and shares its [allow list](https://developers.telnyx.com/docs/agent-gateway/authorization/allow-lists.md), [budget, and rate limits](https://developers.telnyx.com/docs/agent-gateway/traffic/budgets-and-rate-limits.md).

```json theme={null}
{
  "name": "support-agent",
  "team_id": "d7b21324-a2bf-406c-ba49-c6ec4d23d476",
  "expires_in": "30d"
}
```

The response carries the key's value in `key`. Telnyx returns it in this response only. The key's `id` is a hash the instance stores in place of the value, and the API takes the `id` to change or revoke the key.

```json theme={null}
{
  "data": {
    "id": "f739ad190d29e2a5e658c3a486111953e6c18d746fd04374962ab150aae17757",
    "key": "sk-EXAMPLE-KEY-VALUE",
    "name": "support-agent",
    "team_id": "d7b21324-a2bf-406c-ba49-c6ec4d23d476",
    "expires_at": "2026-11-25T16:05:09.835451Z",
    "blocked": false,
    ...
  }
}
```

## Presentation

The agent sends the key to the instance as a bearer token, `Authorization: Bearer <key>`, on every request. The instance refuses a request without a valid key.

## Expiry

`expires_in` sets how long the key works, as a number and a unit (`s`, `m`, `h`, or `d`), such as `30d`. The response shows the resulting `expires_at`. Setting `expires_in` with [`PATCH /v2/agent_gateways/{id}/keys/{key_id}`](https://developers.telnyx.com/api-reference/agent-gateway-keys/update-a-key) counts from the time of the update.

## Blocking and Revocation

`"blocked": true` makes the instance refuse the key. The key keeps its settings and spend, and `"blocked": false` lets it through again.

[`DELETE /v2/agent_gateways/{id}/keys/{key_id}`](https://developers.telnyx.com/api-reference/agent-gateway-keys/delete-a-key) revokes the key and returns it without its value.

Every change to a key reaches the instance within a minute, including a block and a revocation.