Authentication

Every request to the SearchRouter API is authenticated with a Bearer API key.

API keys

API keys are created and managed from your dashboard. Each key looks like sk-sr-... and belongs to an organization. Every inference request resolves its key to an organization, checks the org credit balance and the key's spend limit, then meters usage against both.

Keys are shown only once at creation - store them securely.
Create separate keys per environment or service so you can revoke one without disruption.
Each key can carry its own spend limit, independent of the org balance.

The Authorization header

Pass the key as a Bearer token on every request:

http

Authorization: Bearer sk-sr-...

⚠Keep keys server-side. Never embed an sk-sr- key in client-side code, a public repo, or a mobile app. Proxy requests through your backend.

Verify a key

Call GET /key to confirm a key works and inspect its usage and remaining limit:

bash

curl https://searchrouter.ai/api/v1/key \
  -H "Authorization: Bearer $SR_API_KEY"

json

{
  "label": "production",
  "usage": 12.84,
  "limit": 100.0,
  "limit_remaining": 87.16
}

Field	Type	Description
`label`	string	Human-readable name for the key.
`usage`	number	Total spend attributed to this key, in USD.
`limit`	number \| null	Spend ceiling for the key; null = unlimited (bounded by org balance).
`limit_remaining`	number \| null	Remaining spend before the key limit is hit.

Authentication errors

Missing, malformed, or revoked keys return 401. Insufficient credits return 402. The HTTP status mirrors the error.code field:

json

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

Status	type	Meaning
401	`authentication_error`	Missing or invalid API key.
402	`insufficient_credits`	Org balance or key spend limit exhausted.
403	`permission_error`	Key is not allowed to use this model or provider.
429	`rate_limit_error`	Too many requests; back off and retry.

Bringing your own provider keys (BYOK)

SearchRouter calls upstream providers with managed keys by default. You can instead store your own AES-encrypted provider keys per organization, so usage is billed to your upstream accounts while still routing through one SearchRouter key. See Pricing for details.

← Previous

Quickstart

Routing & Fallback