Docs / Start

Auth

GlobalRouter public APIs use API key authentication. HTTP requests use Bearer tokens, while realtime connections can first exchange for a short-lived session_token.

Authentication method

All public HTTP APIs read the Bearer token from the Authorization header.

Authorization: Bearer $GR_API_KEY

Requests are treated as unauthenticated when the header is missing, the Bearer prefix is absent, the token is empty, the API key does not exist, or the API key is disabled or expired.

Scope and access boundaries

API keys carry scopes, model allowlists, model blocklists, IP allowlists, expiration times, and per-minute rate limits. Each endpoint checks the scope it needs: chat and realtime connections need chat, the model catalog needs models, video, file, and async task APIs need tasks, and key management needs management.

If the tenant is disabled, the required scope is missing, the model is not in the allowlist, the model is blocklisted, or the request IP is outside the allowlist, the API returns an authorization failure.

Realtime session_token

Realtime browser scenarios, or any flow where a long-lived API key should not be exposed, can call POST /v1/realtime/session-token to exchange for a short-lived session_token, then connect with it as a WebSocket query parameter. Realtime authentication failures close the connection; common close codes include 4401, 4403, 4404, and 4429.

Authentication failure responses

GlobalRouter primary APIs use a consistent error envelope. Authentication failures never return plaintext API keys or provider credentials.

HTTP status	code	type	Trigger
401	ROUTER_AUTHENTICATION_FAILED	invalid_request_error	Missing, malformed, or empty Bearer token; API key does not exist, is disabled, or is expired.
403	ROUTER_FORBIDDEN	invalid_request_error	Tenant disabled, insufficient scope, restricted model access, or IP allowlist mismatch.

{
  "error": {
    "code": "ROUTER_AUTHENTICATION_FAILED",
    "message": "Invalid or missing API key",
    "type": "invalid_request_error",
    "request_id": "req_xxx"
  }
}

{
  "error": {
    "code": "ROUTER_FORBIDDEN",
    "message": "API key is missing required scope: chat",
    "type": "invalid_request_error",
    "request_id": "req_xxx"
  }
}

Notes

Server requests should store the full API key only on the server. Frontend UI should show masked values only.
Provider keys, webhook secrets, and tenant-internal credentials must not appear in frontend code or public docs examples.
401 means the identity could not be confirmed; 403 means the identity is known but lacks permission.