Authentication - KiteFrost - TTRPG GM API

API key types

There are two types of API key. Create them on your project’s API Keys page.

Prefix	Type	Use
`pk_...`	Publishable key	Client-side requests, read-only scopes
`sk_...`	Secret key	Server-side requests, full scopes

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

Making authenticated requests

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

curl https://api-staging.kitefrost.ai/v1/characters \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json"

import requests

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

const response = await fetch("https://api-staging.kitefrost.ai/v1/characters", {
  headers: {
    Authorization: "Bearer sk_your_key_here",
    "Content-Type": "application/json",
  },
});

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.

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