Authentication
Bearer keys, required headers, and the response headers on every relay call.
Bearer authentication
Every relay request — HTTP and WebSocket alike — authenticates with a Speko API key:
Authorization: Bearer sk_speko_...The scheme must be exactly Bearer and the token must be a single non-blank string. Failures return 401 with code authentication_failed:
{"error":{"code":"authentication_failed","message":"a Bearer authorization header is required","retryable":false}}See API keys for creating and protecting keys.
Required request headers
| Header | Required on | Notes |
|---|---|---|
Authorization | everything except /healthz, /readyz | Bearer sk_speko_... |
Idempotency-Key | every POST and every WebSocket upgrade | opaque, at most 256 bytes — see Idempotency |
Content-Type | POST bodies | application/json, or multipart/form-data for transcriptions |
GET /v1/models needs only the Authorization header.
Response headers
Every routed response carries correlation and route headers:
| Header | Meaning |
|---|---|
Speko-Request-ID | Stable ID for the request (rreq_...). Quote it in support requests. |
Speko-Attempt-ID | The provider attempt that produced this response. Changes on failover. |
Speko-Provider | Provider that served the request |
Speko-Model | Model that served the request |
Speko-Region | The Speko region that served you — a proximity fact about Speko infrastructure, not a provider data-residency guarantee |
Speko-Usage-Characters | TTS one-shot only: characters metered for the synthesis |
Error responses also carry Speko-Request-ID whenever one was assigned, and the same ID appears as request_id inside the error envelope.
GET /v1/models responses use an edge-local correlation ID of the form req_edge_... rather than rreq_... — listing the catalog does not create an admitted request.