Skip to main content
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.
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.

​
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.