multi-router.aidocs

API Access

Authentication

The headers that carry an API key, and the responses when authentication fails.

Authentication is how a request proves which API key it comes from. Most requests carry the key in the Authorization header as a bearer token. Requests through a Claude Proxy or Codex Proxy may carry the developer's own provider login in that header, so Multi-Router also reads the key from its own header, X-MR-Api-Token, from x-api-key on Claude endpoints, and from x-goog-api-key on Gemini endpoints.

Headers

Multi-Router reads the API key from these headers:

HeaderFormatAccepted on
AuthorizationBearer sk-mr-…Every endpoint.
X-MR-Api-TokenBearer sk-mr-…Every endpoint. Used with a Claude Proxy or Codex Proxy when Authorization carries a provider login.
x-api-keysk-mr-…The endpoints in the next table.
x-goog-api-keysk-mr-…The Gemini Proxy endpoints, /v1beta/models/{model}:generateContent and :streamGenerateContent.

The x-api-key header, as Anthropic clients send it, is accepted on these endpoints:

EndpointCondition
POST /v1/messagesAlways.
POST /v1/messages/count_tokensAlways.
Claude Proxy Bedrock endpoints under /bedrockAlways.
Claude Proxy Vertex endpoints under /vertexAlways.
GET /v1/modelsWith an X-MR-Router header naming a Claude Proxy. Without it, the key goes in Authorization.

Multi-Router reads the first of these headers present on the request, in the order X-MR-Api-Token, Authorization, x-api-key, and authenticates with that header alone. A request therefore carries the key in one header, and an Authorization header holding anything else, such as a provider login, is paired with X-MR-Api-Token. The value is Bearer or bearer, a single space, and the key, exactly as issued.

Examples

The same key works in either header, depending on the endpoint:

Authorization headerbash
curl https://api.multi-router.ai/v1/chat/completions \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "multi-router/rt_9Hk3Ws7PzQ", "messages": [{ "role": "user", "content": "Hello" }] }'
x-api-key header on Messagesbash
curl https://api.multi-router.ai/v1/messages \
  -H "x-api-key: $MR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "multi-router/rt_9Hk3Ws7PzQ", "max_tokens": 256, "messages": [{ "role": "user", "content": "Hello" }] }'

The OpenAI and Anthropic SDKs send their API key setting in these headers, so an SDK works with Multi-Router by setting its base URL to https://api.multi-router.ai/v1 for OpenAI, or https://api.multi-router.ai for Anthropic, and its API key to the Multi-Router key. The Anthropic SDK lists models with x-api-key, so model listing through it takes an X-MR-Router header naming a Claude Proxy.

Keys on proxy requests

On a Claude Proxy with the Developer credential source and on a Codex Proxy without an organization key, the Authorization and x-api-key headers carry the developer's provider login, and the Multi-Router key travels in X-MR-Api-Token. A Multi-Router key found in a header bound for the provider is refused with 400, which keeps the key inside Multi-Router. On Messages, token counting and Responses the message names the header; on the Bedrock and Vertex endpoints it is MR API token in forwarded header. See Agents & Editors.

Errors

A request whose key is missing, unknown, disabled or expired receives 401. The response is the same in every case, which keeps the organization's keys private. Each endpoint uses its own error format, so the OpenAI and Anthropic SDKs report an authentication error:

EndpointStatusResponse
Chat Completions and Responses401{"error":{"message":"invalid or missing API key","type":"authentication_error","code":"invalid_api_key"}}
Messages and token counting401{"type":"error","error":{"type":"authentication_error","message":"invalid or missing API key"}}
Claude Proxy Bedrock and Vertex endpoints401invalid or missing API token, in the Bedrock or Vertex error format

A valid key that lacks a scope receives 403 insufficient_scope, in the same format as the 401 for that endpoint: on Messages and token counting the error type is permission_error. See Scope.

Router AccessRate Limit
Was this helpful?