Authentication

Onlist authenticates every request with a single bearer token. There is no bespoke SDK and no signing scheme to learn: point your existing OpenAI, Anthropic, or Gemini client at https://onlist.io and supply your token.

Bearer token

Issue a token in the Onlist buyer dashboard, then send it on every request in the standard Authorization header:

Authorization: Bearer YOUR_ONLIST_TOKEN

The token is a plain bearer credential tied to your wallet. It carries your account's routing preferences (allow/deny lists) and per-token rate and quota limits. Keep it secret and server-side; rotate it from the dashboard if it leaks.

curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

A missing or invalid token returns 401. See Errors for the full envelope.

No sk-or- prefix

If you are migrating from OpenRouter, drop the prefix. Onlist tokens are plain bearer strings, not sk-or-... keys.

Header variants

Different SDKs send the credential under different header names. Onlist normalizes all of them to the same token, so you do not need to special-case the header your client library uses:

All three resolve to one token and one account. The examples below set authentication the way each official SDK expects.

# OpenAI-compatible surface
curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "openai/gpt-4o", "messages": [{ "role": "user", "content": "Hi" }] }'

# Anthropic-native: x-api-key
curl https://onlist.io/v1/messages \
  -H "x-api-key: YOUR_ONLIST_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "anthropic/claude-opus-4.8", "max_tokens": 256, "messages": [{ "role": "user", "content": "Hi" }] }'

# Gemini-native: x-goog-api-key
curl "https://onlist.io/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contents": [{ "parts": [{ "text": "Hi" }] }] }'

Management keys

An API key spends money; it cannot manage your account. For programmatic key management, balance lookups and usage reporting there is a second, separate credential: a management key, created under Management keys in your account menu. It carries an mgmt_ prefix.

Creating or revoking a management key requires a passkey or 2FA confirmation, and the key itself is shown exactly once. See the Management API for the full endpoint reference.

Sign in with Onlist (OAuth PKCE)

If you are building an application that needs a key for its own users, you do not have to ask each of them to paste one. Send them to Onlist's consent page and receive a key they explicitly authorized:

https://onlist.io/auth?callback_url=http://localhost:9999/cb&code_challenge=<S256>&code_challenge_method=S256

The user confirms — optionally setting a spend cap on the key — and Onlist redirects to your callback with ?code=.... Exchange it, unauthenticated, for the key:

curl -sS -X POST https://onlist.io/api/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{ "code": "THE_CODE", "code_verifier": "YOUR_VERIFIER" }'

The code lasts 10 minutes and can be redeemed once. Full rules, including the callback URL restrictions and the headless (no-callback) mode, are in the Management API.

Attribution headers

OpenRouter clients commonly send HTTP-Referer and X-Title to attribute traffic to an app. Onlist reads the same headers (including the X-OpenRouter-Title and X-OpenRouter-Categories variants), so a setup copied from OpenRouter works unchanged.

These headers place your app on the public Apps & Agents rankings, ranked by token usage. They do not affect routing, model selection, or billing.

Next steps

• Quickstart: Get a token, set your base URL, and make a first request in curl, Python, and Node.
• Errors: The error envelope and what a 401 means when a token is missing, invalid, or stale.