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

# Authentication

> Authenticate API requests using API keys with scoped access control.

## API key types

Every account has two types of API keys:

| Prefix        | Type             | Use                                    |
| ------------- | ---------------- | -------------------------------------- |
| `pk_live_...` | Publishable key  | Client-side requests, read-only scopes |
| `sk_live_...` | Secret key       | Server-side requests, full scopes      |
| `pk_test_...` | Test publishable | Development only, no billing           |
| `sk_test_...` | Test secret      | Development only, no billing           |

<Warning>
  Secret keys (`sk_`) must never be exposed in client-side code, browser bundles, or public repositories.
</Warning>

## Making authenticated requests

Pass your API key as a Bearer token in the `Authorization` header on every request.

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

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

  headers = {
      "Authorization": "Bearer sk_live_your_key_here",
      "Content-Type": "application/json",
  }
  response = requests.get("https://api.kitefrost.io/v1/characters", headers=headers)
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.kitefrost.io/v1/characters", {
    headers: {
      Authorization: "Bearer sk_live_your_key_here",
      "Content-Type": "application/json",
    },
  });
  ```
</CodeGroup>

## Scopes

Keys are issued with one or more scopes. Requests that exceed the key's scope receive `403 Forbidden`.

| Scope        | Description                           |
| ------------ | ------------------------------------- |
| `read`       | Read resources (NPCs, sessions, etc.) |
| `write`      | Create and update resources           |
| `generate`   | Trigger AI generation jobs            |
| `admin`      | Manage API keys, billing, webhooks    |
| `byok:write` | Set or revoke your own LLM API key    |

## Managing keys

Create, rotate, and revoke keys from the **Settings → API Keys** page in your dashboard, or via the [API keys endpoint](/api-reference#tag/api-keys).

## Errors

| HTTP Status | Code                 | Meaning                                      |
| ----------- | -------------------- | -------------------------------------------- |
| `401`       | `unauthorized`       | Missing or malformed `Authorization` header  |
| `401`       | `invalid_api_key`    | Key does not exist or has been revoked       |
| `403`       | `insufficient_scope` | Key lacks the required scope for this action |