> ## 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. # Create gateway token key > 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. ## OpenAPI ````yaml /openapi/source/external/inference/ai-gateway-resources.json post /llm_token_gateway/token_keys openapi: 3.1.0 info: title: AI Gateway configuration version: 1.0.0 description: >- Manage account-scoped AI Gateway groups and inference keys. All mutations require Idempotency-Key; updates and deletes require the current resource ETag in If-Match. Nullable fields clear on null and omitted PATCH fields are preserved. servers: - url: https://api.telnyx.com/v2 security: [] paths: /llm_token_gateway/token_keys: post: tags: - AI Gateway summary: Create gateway token key description: >- 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. operationId: create_token_keys parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TokenKeyCreate' example: name: support-service token_group_id: 11111111-1111-4111-8111-111111111111 max_parallel_requests: 5 responses: '200': description: >- Idempotency replay: metadata only; lost create response requires revoke/new create. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. ETag: schema: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: Quoted integer resource version. content: application/json: schema: $ref: '#/components/schemas/TokenKeyResponse' example: data: record_type: token_key id: 11111111-1111-4111-8111-111111111111 created_at: '2026-10-07T08:00:00Z' updated_at: '2026-10-07T08:00:00Z' version: 1 name: support-backend token_group_id: 11111111-1111-4111-8111-111111111111 token_user_id: null max_budget: 1000 budget_duration: 1d tpm_limit: 10000000 rpm_limit: 6000 allowed_models: null expires_at: null blocked: false required_end_user_id: false spend: 0 reserved_spend: 0 budget_started_at: null resets_at: null max_parallel_requests: 5 provisioning: ready '201': description: OK headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. ETag: schema: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: Quoted integer resource version. content: application/json: schema: $ref: '#/components/schemas/TokenKeyCreatedResponse' example: data: record_type: token_key id: 11111111-1111-4111-8111-111111111111 created_at: '2026-10-07T08:00:00Z' updated_at: '2026-10-07T08:00:00Z' version: 1 name: support-backend token_group_id: 11111111-1111-4111-8111-111111111111 token_user_id: null max_budget: 1000 budget_duration: 1d tpm_limit: 10000000 rpm_limit: 6000 allowed_models: null expires_at: null blocked: false required_end_user_id: false spend: 0 reserved_spend: 0 budget_started_at: null resets_at: null token: ltg_sk_SYNTHETIC_EXAMPLE_NOT_A_VALID_CREDENTIAL max_parallel_requests: 5 provisioning: ready '400': $ref: '#/components/responses/GatewayError400' '401': $ref: '#/components/responses/GatewayError401' '403': $ref: '#/components/responses/GatewayError403' '404': $ref: '#/components/responses/GatewayError404' '409': $ref: '#/components/responses/GatewayError409' '412': $ref: '#/components/responses/GatewayError412' '428': $ref: '#/components/responses/GatewayError428' '429': $ref: '#/components/responses/GatewayError429' '502': $ref: '#/components/responses/GatewayError502' '503': $ref: '#/components/responses/GatewayError503' '504': $ref: '#/components/responses/GatewayError504' security: - telnyxApiKey: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_-]+$ description: >- 24h, scoped by account+method+path. Same key/body returns same outcome; changed body 409; in-progress 409 with Retry-After. Token-create replay returns 200 metadata WITHOUT secret. schemas: TokenKeyCreate: type: object additionalProperties: false properties: max_parallel_requests: anyOf: - type: integer minimum: 1 maximum: 1000 description: >- 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. - type: 'null' name: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ token_group_id: type: string format: uuid token_user_id: anyOf: - type: string format: uuid - type: 'null' max_budget: anyOf: - $ref: '#/components/schemas/Money' minimum: 0.000001 maximum: 1000 - type: 'null' description: >- Omitted or null defaults to the maximum (1000 USD) (on a blocked key, null is kept until the key is unblocked); a value below the minimum (0.000001 USD) 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. The default budget is lifetime unless budget_duration is set. Budgets and spend are an enforcement guard computed at one flat placeholder rate for every Telnyx-hosted model (rate_version telnyx-reference-v1: 5 USD per million input and 15 USD per million output tokens), not the customer's bill; Telnyx Inference usage is billed separately at the model's actual price. budget_duration: $ref: '#/components/schemas/BudgetDuration' tpm_limit: anyOf: - type: integer minimum: 1 maximum: 10000000 - type: 'null' description: >- 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: anyOf: - type: integer minimum: 1 maximum: 6000 - type: 'null' description: >- 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: anyOf: - type: array items: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ uniqueItems: true maxItems: 1000 - type: 'null' expires_at: anyOf: - type: string format: date-time - type: 'null' blocked: type: boolean required_end_user_id: type: boolean default: false description: >- Require a nonempty caller-asserted end-user ID; not proof of identity. required: - name - token_group_id TokenKeyResponse: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/TokenKey' required: - data TokenKeyCreatedResponse: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/TokenKeyCreated' required: - data Money: type: number minimum: 0 maximum: 1000000000 multipleOf: 0.000001 description: >- USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting. BudgetDuration: type: - string - 'null' enum: - 1d - 7d - 30d - null TokenKey: type: object additionalProperties: false properties: record_type: const: token_key id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time version: type: integer minimum: 1 max_parallel_requests: anyOf: - type: integer minimum: 1 maximum: 1000 description: >- 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. - type: 'null' name: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ token_group_id: type: string format: uuid token_user_id: anyOf: - type: string format: uuid - type: 'null' max_budget: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: >- 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). budget_duration: $ref: '#/components/schemas/BudgetDuration' tpm_limit: anyOf: - type: integer minimum: 0 - type: 'null' description: >- 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: anyOf: - type: integer minimum: 0 - type: 'null' description: >- 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: anyOf: - type: array items: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ uniqueItems: true maxItems: 1000 - type: 'null' expires_at: anyOf: - type: string format: date-time - type: 'null' blocked: type: boolean required_end_user_id: type: boolean default: false description: >- Require a nonempty caller-asserted end-user ID; not proof of identity. spend: $ref: '#/components/schemas/Money' reserved_spend: $ref: '#/components/schemas/Money' budget_started_at: anyOf: - type: string format: date-time - type: 'null' resets_at: anyOf: - type: string format: date-time - type: 'null' provisioning: type: string enum: - ready - pending - unavailable - inactive - unsupported - unknown description: >- 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. required: - record_type - id - created_at - updated_at - version - name - token_group_id - token_user_id - max_budget - budget_duration - tpm_limit - rpm_limit - allowed_models - expires_at - blocked - required_end_user_id - spend - reserved_spend - budget_started_at - resets_at TokenKeyCreated: type: object additionalProperties: false properties: record_type: const: token_key id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time version: type: integer minimum: 1 max_parallel_requests: anyOf: - type: integer minimum: 1 maximum: 1000 description: >- 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. - type: 'null' name: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ token_group_id: type: string format: uuid token_user_id: anyOf: - type: string format: uuid - type: 'null' max_budget: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: >- 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). budget_duration: $ref: '#/components/schemas/BudgetDuration' tpm_limit: anyOf: - type: integer minimum: 0 - type: 'null' description: >- 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: anyOf: - type: integer minimum: 0 - type: 'null' description: >- 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: anyOf: - type: array items: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ uniqueItems: true maxItems: 1000 - type: 'null' expires_at: anyOf: - type: string format: date-time - type: 'null' blocked: type: boolean required_end_user_id: type: boolean default: false description: >- Require a nonempty caller-asserted end-user ID; not proof of identity. spend: $ref: '#/components/schemas/Money' reserved_spend: $ref: '#/components/schemas/Money' budget_started_at: anyOf: - type: string format: date-time - type: 'null' resets_at: anyOf: - type: string format: date-time - type: 'null' provisioning: type: string enum: - ready - pending - unavailable - inactive - unsupported - unknown description: >- 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. token: type: string pattern: ^ltg_sk_[A-Za-z0-9_-]+$ readOnly: true required: - record_type - id - created_at - updated_at - version - name - token_group_id - token_user_id - max_budget - budget_duration - tpm_limit - rpm_limit - allowed_models - expires_at - blocked - required_end_user_id - spend - reserved_spend - budget_started_at - resets_at - token Error: type: object additionalProperties: false properties: errors: type: array items: $ref: '#/components/schemas/ErrorItem' minItems: 1 required: - errors ErrorItem: type: object additionalProperties: false properties: code: type: string enum: - invalid_request - invalid_token_key - unauthorized - token_key_blocked - resource_blocked - budget_exceeded - end_user_budget_exceeded - model_not_in_catalog - rate_limit_exceeded - concurrency_limit_exceeded - not_found - conflict - idempotency_conflict - precondition_failed - precondition_required - enforcement_unavailable - upstream_error - upstream_timeout - limit_out_of_range - prompt_blocked - response_blocked - invalid_metadata - cursor_expired title: type: string detail: type: string meta: type: object additionalProperties: false properties: scope: $ref: '#/components/schemas/Scope' resets_at: anyOf: - type: string format: date-time - type: 'null' request_id: type: string format: uuid required: - request_id required: - code - title - detail - meta Scope: type: string enum: - token_group - token_user - token_key - end_user responses: GatewayError400: description: >- Invalid fields or values (invalid_request), or token-key budget/rate limits outside their supported range (limit_out_of_range). headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: invalid_request title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError401: description: Wrong/missing credential for this plane. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. WWW-Authenticate: schema: type: string description: >- Bearer challenge for this plane; no provider/master credential disclosure. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: unauthorized title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError403: description: >- Blocked/expired, exhausted budget or disallowed model; scope identifies exhausted level. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: unauthorized title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError404: description: Absent or foreign-account resource (indistinguishable). headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: not_found title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError409: description: Membership, idempotency or snapshot conflict. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: idempotency_conflict title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError412: description: ETag mismatch. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: precondition_failed title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError428: description: If-Match required. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: precondition_required title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError429: description: Rate limited. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: rate_limit_exceeded title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError502: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: invalid_request title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError503: description: Enforcement/secret/managed route unavailable; fail closed. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: enforcement_unavailable title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError504: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: invalid_request title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 securitySchemes: telnyxApiKey: type: http scheme: bearer description: Management-only Telnyx account credential. ````