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. Every field is optional, and a key’s name is unique on the instance. A key with a team_id belongs to that team and shares its allow list, budget, and rate limits.

{
  "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.

{
  "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} 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} 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.