Authentication

OxyRouter has two authentication modes:

Surface	Credential	Used by
Inference API	API key (oxy_sk_...)	/v1/chat/completions, /v1/models
Public catalogue	None	/v1/catalog/models

API keys authenticate inference requests only. Dashboard and account management happen in the web app and are not part of this API.

API keys

Create keys in the dashboard under API keys. The secret is returned exactly once in the creation response and is stored only as a peppered HMAC-SHA256 digest.

Sending the key

Use either header. Authorization: Bearer is preferred.

Authorization: Bearer oxy_sk_...

X-API-Key: oxy_sk_...

Scopes

Scope	Grants
inference:read	GET /v1/models, GET /v1/models/{model_id}
inference:write	POST /v1/chat/completions
usage:read	Reserved for key-based usage reads

Keys created without an explicit scope list receive all three scopes. A key missing a required scope receives 403 with code api_key_scope_denied.

For least privilege, issue separate keys for read-only discovery and for inference, and give each key an expiry date when it is temporary.

Key lifecycle

• Keys use the prefix oxy_sk_.
• Listing a key returns only its display prefix, for example oxy_sk_ab12.
• Expired keys are rejected with 401 api_key_expired.
• Revoked keys stop working immediately and permanently.
• last_used_at is updated on a best-effort basis.

Keys are created and revoked from the dashboard under API keys. Account and billing actions live in the dashboard, not in the inference API.

Caution

Never ship an API key in client-side code, commit it to source control, or log it. Store it in a secret manager or environment variable. Rotate by creating a new key and revoking the old one.

Scope errors

Status	Code	Meaning
401	invalid_api_key	Header missing or key not recognised
401	api_key_expired	Key past its expires_at
403	api_key_scope_denied	Key lacks the scope required by the endpoint

Public endpoints

GET /v1/catalog/models requires no authentication and returns the enabled models with their retail USD pricing.