Authentication

This page covers how a request is authenticated: the two headers that carry a key, the key format and tiers, how to handle keys, every 401 the API returns, and how quickly a revoked key stops working. You need it before your first request and again when a key is rotated.

Sending the key

Send the key in the X-API-Key header:

curl -s https://api.routeur.app/v1/status -H "X-API-Key: $ROUTEUR_API_KEY"

or as a bearer token:

curl -s https://api.routeur.app/v1/status -H "Authorization: Bearer $ROUTEUR_API_KEY"

Header	Value	Notes
`X-API-Key`	`rk_live_...`	Preferred.
`Authorization`	`Bearer rk_live_...`	Read only when `X-API-Key` is absent.

Both headers work on every /v1 endpoint, on the live stream and on the MCP endpoint. The stream cannot be opened from a browser EventSource, which cannot set headers; connect from a server.

Key format and tiers

A key is rk_live_<id>_<secret>:

Part	Format	Example
Prefix	`rk_live_`	`rk_live_`
Id	12 characters, `a-z` and `0-9`	`yt0qufb8kj5o`
Secret	43 characters, `A-Za-z0-9_-` (base64url of 32 random bytes)	shown once when issued

Routeur stores only the SHA-256 of the secret. A lost key cannot be shown again; ask for a new one and have the old one revoked. Every key has a tier that sets its per-minute limit and daily quota. Custom limits can be set on a key when it is issued.

Tier	Requests per minute	Requests per day
`free`	30	2,000
`trader`	120	50,000
`pro`	600	500,000
`institutional`	3,000	10,000,000

The limits in force for your key come back on every response in X-RateLimit-Limit and X-Daily-Quota-Limit; see Rate limits.

Handling keys

Keep keys on your server, in an environment variable or a secret store. A key in a browser, a mobile app or a public repository can be read and used against your quota.
Use one key per system so that revoking one does not stop the others.
To rotate, ask for a new key, deploy it, then have the old one revoked.
Nothing in the API reads or writes your key beyond checking it: there is no endpoint to list, create or revoke keys.

Errors

A request without a valid key returns 401 with WWW-Authenticate: Bearer realm="routeur", Cache-Control: no-store and the standard error body.

Status	Code	When
401	`api_key_required`	Neither header carried a credential.
401	`invalid_api_key`	The credential starts with `rk_` but is malformed, unknown, or its secret does not match.
401	`api_key_revoked`	The key exists but was revoked.
401	`invalid_token`	The credential does not start with `rk_`. Such credentials are checked as identity tokens for Routeur’s own services and fail for everyone else. A key pasted with a typo in its prefix lands here.

Observed:

curl -s https://api.routeur.app/v1/status

{"error":{"code":"api_key_required","message":"Send an API key in the X-API-Key header or as a Bearer token."}}

curl -s https://api.routeur.app/v1/status -H "X-API-Key: rk_live_000000000000_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

{"error":{"code":"invalid_api_key","message":"The API key is not valid."}}

A 401 is not counted against any limit. /healthz and unknown paths (404 not_found) do not need a key.

Revocation lag

Each API instance caches what it knows about a key for one minute, so a revoked key can keep working for up to 60 seconds on an instance that checked it just before the revocation. The same cache applies to unknown keys: a key used before it was created is refused with invalid_api_key for up to a minute on that instance. Retry after a minute.

MCP

The MCP endpoint https://api.routeur.app/mcp takes the same key in the same headers. Protocol messages such as initialize and tools/list are authenticated but not counted; the REST requests a tool makes are counted as usual. A request without a key gets the same 401 as REST:

curl -s -D - -X POST https://api.routeur.app/mcp -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs","version":"0"}}}'

HTTP/2 401
www-authenticate: Bearer realm="routeur"

{"error":{"code":"api_key_required","message":"Send an API key in the X-API-Key header or as a Bearer token."}}

See Agents and MCP.

Get started

Concepts

Agents & MCP

Webhooks

Reference

Sending the key

Key format and tiers

Handling keys

Errors

Revocation lag

MCP

Sending the key

Key format and tiers

Handling keys

Errors

Revocation lag

MCP

Related