> ## Documentation Index
> Fetch the complete documentation index at: https://game-narrative.docs.kitefrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Key (BYOK)

> Route AI generation through your own LLM API keys to control costs and access frontier models.

## Overview

By default, all AI generation is billed through the platform's model pool at a per-generation rate. With **BYOK**, you supply your own API key for a supported LLM provider. Generation costs are then charged directly to your provider account - platform fees still apply for compute, storage, and tooling.

BYOK is available on **Pro** and **Enterprise** plans.

## Supported providers

| Provider  | Key prefix   |
| --------- | ------------ |
| OpenAI    | `sk-...`     |
| Anthropic | `sk-ant-...` |
| Google    | varies       |
| Groq      | `gsk_...`    |

The `model_preference` field lets you specify which of your provider's models to use. Consult your provider's documentation for available model identifiers.

## Set your key

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.kitefrost.io/v1/byok \
    -H "Authorization: Bearer sk_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "openai",
      "api_key": "sk-your-openai-key",
      "model_preference": "<your-model-id>"
    }'
  ```

  ```python Python theme={null}
  import requests

  requests.put(
      "https://api.kitefrost.io/v1/byok",
      headers={"Authorization": "Bearer sk_live_your_key_here"},
      json={
          "provider": "openai",
          "api_key": "sk-your-openai-key",
          "model_preference": "<your-model-id>",
      },
  )
  ```

  ```typescript TypeScript theme={null}
  await fetch("https://api.kitefrost.io/v1/byok", {
    method: "PUT",
    headers: {
      Authorization: "Bearer sk_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "openai",
      api_key: "sk-your-openai-key",
      model_preference: "<your-model-id>",
    }),
  });
  ```
</CodeGroup>

Your key is encrypted at rest using AES-256-GCM and is never returned in API responses.

## Check key status

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.kitefrost.io/v1/byok \
    -H "Authorization: Bearer sk_live_your_key_here"
  ```

  ```json Response theme={null}
  {
    "provider": "openai",
    "model_preference": "<your-model-id>",
    "status": "active",
    "last_verified_at": "2026-03-18T10:00:00Z",
    "key_hint": "sk-...xJ4q"
  }
  ```
</CodeGroup>

## Revoke your key

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.kitefrost.io/v1/byok \
    -H "Authorization: Bearer sk_live_your_key_here"
  ```
</CodeGroup>

After revocation the platform reverts to its default model pool. Any in-flight generation jobs complete using the previously cached credentials before expiry.

## Security notes

* Keys are stored encrypted; only the last 4 characters are ever displayed.
* Rotating your provider key: call `PUT /v1/byok` with the new key - the old one is overwritten atomically.
* The scope `byok:write` is required on the API key used to set or revoke a BYOK entry.