Authentication

Sakrylle API accepts two credential types:

• Manual API key: sk-xxxxxxxxxxxxxxxx
• OAuth access token: sk_oauth_xxxxxxxxxxxxxxxx

Both are sent in request headers. Do not put credentials in the query string.

Manual API keys

Supported headers

Method	Example	Notes
Authorization: Bearer	Authorization: Bearer sk-xxxxxxxxxxxxxxxx	Recommended default
x-api-key	x-api-key: sk-xxxxxxxxxxxxxxxx	Compatibility for some Anthropic-style clients
x-goog-api-key	x-goog-api-key: sk-xxxxxxxxxxxxxxxx	Compatibility for clients that expect a Google-style header

WARNING

Send only one authentication header per request.

Create an API key

1. Sign in to the Console.
2. Open the API Keys page.
3. Click New API Key and optionally add a label.
4. Copy the sk-... value and store it safely.

Verify a key

The quickest health check is GET /v1/models:

curl https://api.sakrylle.com/v1/models \
  -H "Authorization: Bearer $SAKRYLLE_API_KEY"

OAuth access tokens

OAuth tokens should be sent with Authorization: Bearer:

Authorization: Bearer sk_oauth_xxxxxxxxxxxxxxxx

OAuth permissions are scope-based. The most common scopes in this docs set:

Scope	Purpose
profile:read	Read /v1/me.user
account:read	Read /v1/me.account, current_group, allowed_groups, and related account state
account:balance:read	Read balance fields

Group selection

OAuth tokens can switch groups in the model field:

curl https://api.sakrylle.com/v1/chat/completions \
  -H "Authorization: Bearer sk_oauth_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "3:gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The format is always <group_id>:<model>. group_id is a numeric ID, not a string alias.

If the prefix is omitted, the gateway uses the token's default bound group.

All group models

curl "https://api.sakrylle.com/v1/models?groups=all" \
  -H "Authorization: Bearer sk_oauth_xxxxxxxxxxxxxxxx"

This query parameter only works for OAuth tokens. Manual API keys ignore it.

See Models API.

Deprecated keys

Passing credentials via ?key=... or ?api_key=... is deprecated and returns 400:

{
  "error": {
    "message": "Passing API key via query parameter is not supported. Use the Authorization header instead.",
    "type": "invalid_request_error",
    "code": "api_key_in_query_deprecated"
  }
}

Security tips

WARNING

An API key is equivalent to a password: anyone holding it can spend your quota.

• Put the key in an environment variable:

  export SAKRYLLE_API_KEY=sk-xxxxxxxxxxxxxxxx

• Use separate keys for development, staging, and production.
• Revoke and replace leaked keys immediately.
• Never hard-code keys in browser or mobile apps.
• Never expose full keys in public issues, screenshots, or logs.

Auth errors

Status	Meaning	Typical cause
401 Unauthorized	Missing auth header, invalid key, or expired token	Missing Bearer prefix, typo, expired OAuth token
403 Forbidden	Key/token is valid, but group or scope does not allow access	Model not enabled for the group, OAuth scope missing
402-class error	Balance or quota exhausted	Wallet depleted, subscription expired
429 Too Many Requests	Rate limit hit	Too much concurrency, many clients sharing one key

See Errors for the full table.