Authentication

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

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.kitefrost.io/v1/characters \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json"

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)

const response = await fetch("https://api.kitefrost.io/v1/characters", {
  headers: {
    Authorization: "Bearer sk_live_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

Getting Started

Core Concepts

API Reference

API key types

Making authenticated requests

Scopes

Managing keys

Errors

​API key types

​Making authenticated requests

​Scopes

​Managing keys

​Errors

API key types

Making authenticated requests

Scopes

Managing keys

Errors