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

# Bring Your Own Key

> Attach your own OpenAI or Anthropic key to AI Gateway groups so your provider bills inference directly, while Telnyx keeps enforcing budgets, rate limits and attribution.

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](/docs/inference/ai-gateway/inference-api#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

<Steps>
  <Step title="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.

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/llm_token_gateway/provider_keys \
      -H "Authorization: Bearer $TELNYX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "name": "anthropic-production",
        "provider": "anthropic",
        "secret": "<provider-secret>"
      }'
    ```

    ```json theme={null}
    {
      "data": {
        "record_type": "provider_key",
        "id": "2d4f6a8b-1c3e-4a5b-9d7f-0e1a2b3c4d5e",
        "name": "anthropic-production",
        "provider": "anthropic",
        "version": 1,
        "created_at": "2026-09-22T10:00:00Z",
        "updated_at": "2026-09-22T10:00:00Z"
      }
    }
    ```

    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    curl -X PATCH "https://api.telnyx.com/v2/llm_token_gateway/token_groups/$GROUP_ID" \
      -H "Authorization: Bearer $TELNYX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "If-Match: $GROUP_ETAG" \
      -d '{
        "allowed_models": ["Kimi-K3", "claude-sonnet-5"],
        "provider_key_ids": ["2d4f6a8b-1c3e-4a5b-9d7f-0e1a2b3c4d5e"]
      }'
    ```
  </Step>

  <Step title="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](/docs/inference/ai-gateway/inference-api#anthropic-sdk).
  </Step>
</Steps>

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](/docs/inference/ai-gateway/controls#budgets-and-billing), 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:

```bash theme={null}
PROVIDER_KEY_ETAG=$(curl -sS -I "https://api.telnyx.com/v2/llm_token_gateway/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  | awk 'tolower($1) == "etag:" { sub(/\r$/, "", $2); print $2 }')

curl -X DELETE "https://api.telnyx.com/v2/llm_token_gateway/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "If-Match: $PROVIDER_KEY_ETAG"
```

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.