Skip to main content
By default, a token group uses Telnyx-hosted models and usage is billed to your Telnyx account. With bring your own key (BYOK), you store an OpenAI or Anthropic key through the management API and attach it to one or more groups. Requests on bring-your-own-key models from those groups run on your provider account, and your provider bills them. BYOK changes who is billed. It does not change attribution, budget enforcement or rate limiting: key, user, group and end-user controls apply exactly as they do for Telnyx-hosted models.

​
Set up BYOK

1

Create a provider key

POST /provider_keys with a name, the provider (openai or anthropic) and the secret. The secret is accepted only on create and is never returned by any response, list or idempotent replay.
Never keep a logged copy of the request that contains the secret. GET /provider_keys lists provider keys and GET /provider_keys/{id} reads one; neither shows the secret.
2

Attach the key to a group

Reference the provider key in the group’s provider_key_ids, and include the BYOK models you want in allowed_models. A group holds at most one key per provider, the key’s provider must match at least one BYOK model the group allows, and the key and group must be in the same account.Set both when creating a group, or update an existing group with an ETag-protected PATCH. allowed_models is replaced as a whole, so include every model the group should keep:
3

Call models with the token key

Applications keep using their ltg_sk_ token key exactly as before. Never place the provider secret in SDK configuration or application code. Call BYOK models on /v1/chat/completions; Anthropic BYOK models also work on /v1/messages with the Anthropic SDK.
A BYOK model works only when the calling key’s group has an attached provider key for that model’s provider. Without one, requests fail with 503 and code enforcement_unavailable. They never fall back to a Telnyx-hosted model.

​
Billing and reporting

  • Requests on BYOK models are billed by your provider on your provider account, not by Telnyx.
  • AI Gateway budgets and rate limits still apply.
  • Usage reporting records every BYOK request. Its cost is the budget reference valuation, not a Telnyx charge.

​
Rotate a provider secret

Provider keys cannot be edited; PATCH returns 405. To change a secret, create a new provider key, attach it to each group in place of the old one, then delete the old provider key.

​
Delete a provider key

DELETE /provider_keys/{id} requires the provider key’s current ETag in If-Match. Read the key first to get it:
Deleting a provider key detaches it from every group that references it. Requests already in progress complete; new requests on that provider’s models from those groups fail with 503 until another key for the provider is attached.