Authentication & API keys

Every gateway request authenticates with a OneHop API key. Keys are scoped to your account, billed against your prepaid wallet, and can be revealed, restricted, or revoked at any time from the Platform console.

Create a key

Open the console and go to API keys.
Create a key and give it a name you'll recognize later (for example prod-backend or local-dev).
Copy the key. OneHop stores keys reversibly, so you can also re-reveal the plaintext later from the same page — handy for tools like cc-switch.

Keep keys server-side

Treat a key like a password. Never ship it in client-side code or commit it to a repository. Prefer an environment variable such as ONEHOP_API_KEY.

Send the key

OneHop accepts the same header your SDK already sends, depending on the protocol family:

# OpenAI-compatible (recommended for most clients)
Authorization: Bearer $ONEHOP_API_KEY

# Anthropic-compatible
x-api-key: $ONEHOP_API_KEY

# Google GenAI / Vertex-compatible
x-goog-api-key: $ONEHOP_API_KEY

Send exactly one of these. If you send two key headers at once, the request is rejected with AMBIGUOUS_API_KEY (HTTP 400). A missing key returns 401 in the error shape of the entry protocol.

curl https://api.onehop.ai/v1/chat/completions \
  -H "Authorization: Bearer $ONEHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "ping" }]
  }'

Restrict and rotate

Keys can carry guardrails so a leaked credential has limited blast radius:

Allowed models

Limit a key to a subset of models. A request for any other model is rejected instead of billed.

Expiry

Set an expiry date for short-lived or temporary integrations.

Revoke

Revoke a key immediately from the console. Revoked keys return INVALID_API_KEY on the next request.

Re-reveal

Re-reveal the plaintext of an existing key without rotating it.

Common authentication errors

Error	HTTP	Meaning
`API_KEY_REQUIRED`	401	No key header was sent.
`INVALID_API_KEY`	401	Key does not exist or was revoked.
`AMBIGUOUS_API_KEY`	400	More than one key header was sent.
`USER_BLOCKED`	403	The owning account is disabled.

See Rate limits & errors for the full error contract.