---
title: "Create gateway token key"
method: POST
path: "/llm_token_gateway/token_keys"
tags: ["AI Gateway"]
---

# Create gateway token key

`POST /llm_token_gateway/token_keys`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/llm_token_gateway/token_keys`
- Auth: HTTP bearer

Create gateway token key within the authenticated Telnyx account. Foreign and unknown resource IDs return the same 404 response. The token secret is returned only on the original create response. A replay returns metadata without the secret. Provisioning is advisory; ready is not a guarantee of inference availability.

## Headers

- `Idempotency-Key` string, required

## Request body

- TokenKeyCreate
  - `max_parallel_requests` integer, nullable: Optional maximum concurrent reserved/dispatched cache misses across replicas. Null means no concurrency cap. Cache hits do not consume slots; unknown usage retains its budget hold without a slot.
  - `name` string, required
  - `token_group_id` string, uuid, required
  - `token_user_id` string, uuid, nullable
  - `max_budget` number: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
  - `budget_duration` '1d' | '7d' | '30d' | 'null', nullable
  - `tpm_limit` integer, nullable: Omitted or null defaults to the maximum (10000000) (on a blocked key, null is kept until the key is unblocked); a value below the minimum (1) or above the maximum is rejected with 400 limit_out_of_range; a malformed value (negative, wrong type or precision) is 400 invalid_request. Block the key (blocked: true) to deny it; blocking is always accepted.
  - `rpm_limit` integer, nullable: Omitted or null defaults to the maximum (6000) (on a blocked key, null is kept until the key is unblocked); a value below the minimum (1) or above the maximum is rejected with 400 limit_out_of_range; a malformed value (negative, wrong type or precision) is 400 invalid_request. Block the key (blocked: true) to deny it; blocking is always accepted.
  - `allowed_models` string[], nullable
  - `expires_at` string, date-time, nullable
  - `blocked` boolean
  - `required_end_user_id` boolean: Require a nonempty caller-asserted end-user ID; not proof of identity.

## Response `200`

Idempotency replay: metadata only; lost create response requires revoke/new create.

- TokenKeyResponse
  - `data` TokenKey, required
    - `record_type` 'token_key', required
    - `id` string, uuid, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `version` integer, required
    - `max_parallel_requests` integer, nullable: Optional maximum concurrent reserved/dispatched cache misses across replicas. Null means no concurrency cap. Cache hits do not consume slots; unknown usage retains its budget hold without a slot.
    - `name` string, required
    - `token_group_id` string, uuid, required
    - `token_user_id` string, uuid, nullable, required
    - `max_budget` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
    - `budget_duration` '1d' | '7d' | '30d' | 'null', nullable, required
    - `tpm_limit` integer, nullable, required: Stored key limit; set to the maximum when the key was written without one (on a blocked key, null is kept until the key is unblocked).
    - `rpm_limit` integer, nullable, required: Stored key limit; set to the maximum when the key was written without one (on a blocked key, null is kept until the key is unblocked).
    - `allowed_models` string[], nullable, required
    - `expires_at` string, date-time, nullable, required
    - `blocked` boolean, required
    - `required_end_user_id` boolean, required: Require a nonempty caller-asserted end-user ID; not proof of identity.
    - `spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
    - `reserved_spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
    - `budget_started_at` string, date-time, nullable, required
    - `resets_at` string, date-time, nullable, required
    - `provisioning` 'ready' | 'pending' | 'unavailable' | 'inactive' | 'unsupported' | 'unknown': Provisioning state of the key's current policy. `pending`: retry readiness with bounded backoff (treat `unknown` the same). `inactive` and `unsupported` are terminal until the key, group, user or catalog changes. `unavailable` means provisioning is stuck and is retried slowly; surface it. Absent while the gateway runs in compatibility mode.

## Other responses

- `201`: OK
- `400`: Invalid fields or values (invalid_request), or token-key budget/rate limits outside their supported range (limit_out_of_range).
- `401`: Wrong/missing credential for this plane.
- `403`: Blocked/expired, exhausted budget or disallowed model; scope identifies exhausted level.
- `404`: Absent or foreign-account resource (indistinguishable).
- `409`: Membership, idempotency or snapshot conflict.
- `412`: ETag mismatch.
- `428`: If-Match required.
- `429`: Rate limited.
- `502`: upstream_error: every admitted provider attempt, including configured group retries and fallbacks, failed before the first provider event; streams return this real status instead of 200 plus an SSE error. Retrying is not idempotent.
- `503`: Enforcement/secret/managed route unavailable; fail closed.
- `504`: upstream_timeout: as 502 upstream_error, but the last admitted attempt timed out waiting for the provider (connect, read or write timeout, the attempt deadline, or x-ltg-request-timeout) before its first event. Retrying is not idempotent.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-15** `da303e40b51e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/llm_token_gateway/token_keys/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)