Developer docs

keyone sits between your code and the providers. You point your SDK at keyone, use a project key as the API key, and every call is attributed to its client and project and checked against its limits.

To connect a project, change two things in your OpenAI or Anthropic SDK: the base URL and the API key. Streaming, tools and provider headers pass through unchanged.

Quickstart

Create a client and a project in the dashboard, copy the project key, then point your SDK at keyone.

from openai import OpenAI
from anthropic import Anthropic

# OpenAI SDK
client = OpenAI(
    base_url="https://getkeyone.com/api/proxy/openai/v1",
    api_key="kone_live_…",
)

# Anthropic SDK, same key
claude = Anthropic(
    base_url="https://getkeyone.com/api/proxy/anthropic",
    api_key="kone_live_…",
)

Or let the installer do it. Run this in the project root: it asks for the key with a hidden prompt, writes it to your git-ignored env file, rewires the OpenAI, Anthropic, Vercel AI SDK and LangChain clients it recognises, and makes one test call.

npx keyone-cli setup --apply

By convention the key and base URLs live in your env file:

KEYONE_API_KEY=kone_live_…
KEYONE_OPENAI_BASE_URL=https://getkeyone.com/api/proxy/openai/v1
KEYONE_ANTHROPIC_BASE_URL=https://getkeyone.com/api/proxy/anthropic
KEYONE_PERPLEXITY_BASE_URL=https://getkeyone.com/api/proxy/perplexity

Production hosts need the same variables set in their own settings.

Keys

There are two kinds of key.

A project key belongs to one client project. It is shown once, when it is issued or rotated; keyone keeps only its hash. Issue or rotate project keys from the project page, and create agency keys in Settings.

Send either key as a bearer token, or as the API key in an SDK:

curl -X POST https://getkeyone.com/api/proxy/openai \
  -H "Authorization: Bearer kone_live_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5-mini","messages":[{"role":"user","content":"Hello"}]}'

Providers and endpoints

These endpoints go through the same base URL with the project key. Anything else answers 404 unsupported_endpoint.

Streaming works as it does with the provider. Realtime (WebSocket) APIs are not proxied. For transcriptions, ask for json or verbose_json so the duration can be billed.

The live list of tools, models and prices is on the catalog page.

Model shortcuts

Instead of a model name, model can be cheapest, balanced or best. keyone resolves it for that provider from its price table and returns the model it chose in the X-Model-Resolved header.

client.chat.completions.create(
    model="cheapest",
    messages=[{"role": "user", "content": "Summarise this ticket."}],
)

Response headers

Every response carries what the call cost, so your own logs can record it.

Checking a budget

Before a large job, ask what the key has left:

curl https://getkeyone.com/api/proxy/status \
  -H "Authorization: Bearer kone_live_…"

It returns month-to-date spend, the monthly budget and what remains, the per-call cap, allowed tools, the wallet balance and when budgets reset.

Blocked calls

A 403 with "status": "BLOCKED" means a spend control refused the call before it reached the provider. Nothing was sent, and retrying the same call will be refused again.

{
  "status": "BLOCKED",
  "reason": "project_monthly_budget",
  "message": "Project \"Site reports\" has spent $100.0000 of its $100.00 monthly budget.",
  "controls": [
    {
      "type": "PROJECT_MONTHLY_BUDGET",
      "limit_usd": 100,
      "spent_usd": 100,
      "remaining_usd": 0,
      "resets_at": "2026-11-01T00:00:00Z"
    }
  ],
  "hint": "You can request more budget: POST /api/proxy/requests …"
}

The reason is also returned in the X-Blocked-Reason header.

Requesting more budget

When a call is blocked by a monthly budget, the key can ask for more, with a reason and a specific amount:

curl -X POST https://getkeyone.com/api/proxy/requests \
  -H "Authorization: Bearer kone_live_…" \
  -H "Content-Type: application/json" \
  -d '{"requested_budget_usd": 75, "reason": "Monthly newsletter run needs about $60; the cap is $50"}'

Small increases can be approved automatically; the response then says "status": "approved". Otherwise the agency owner gets an email with approve and deny links. Poll GET /api/proxy/requests for the decision. File one request per block, not one per retry.

Empty wallet

A 402 means the agency wallet is empty, or holds less than the call could cost (estimated_call_usd in the response; lower max_tokens or use a cheaper model). The response includes the balance and a link to top up. Only the agency owner can add funds.

MCP server

Agents can manage keyone through its MCP server, using an agency key:

claude mcp add --transport http keyone https://getkeyone.com/api/mcp \
  --header "Authorization: Bearer kone_admin_…"

REST API

The same operations are available over REST, with an agency key in the Authorization header.