Reference
Authentication
API keys, where each surface takes them, and what a missing or wrong key gets back.
API keys#
Every request to the router carries one of your org’s API keys: tcr_ followed by 43 characters.
- Create them in the dashboard under API keys. A key is shown once, when you create it; the router keeps only a hash of it, so a lost key can’t be recovered, only replaced.
- Every key in an org shares its cache, provider keys and retention. Use one per agent or environment, so you can revoke one alone.
- A new key works at once. A deleted key is refused within a few seconds, including on connections already open.
- Keep keys server-side, in your agent’s secrets. Never ship one in a browser or a mobile app.
To check a key, list your stored provider keys with it:
curl https://api.ttscacherouter.dev/v1/provider-keys \ -H "Authorization: Bearer $TTS_CACHE_ROUTER_API_KEY"Where to send it#
The router's own endpoints take it as a bearer token. The drop-ins take it wherever the provider's API takes its key, so the provider's clients work unchanged.
| Endpoint | Header |
|---|---|
| /v1/stream (WebSocket) | Authorization: Bearer tcr_… |
| /v1/audio/speech | Authorization: Bearer tcr_… |
| /v1/provider-keys | Authorization: Bearer tcr_… |
| /sarvam/… | api-subscription-key: tcr_… |
| /raya/… | X-API-Key: tcr_… |
| /elevenlabs/… | xi-api-key: tcr_… |
GET /v1/models, GET /openapi.json and GET /healthz need no key. In the LiveKit plugin, the key is api_key= or TTS_CACHE_ROUTER_API_KEY; in a provider’s own plugin or SDK, it goes where the provider key went.
Provider keys#
Your Sarvam, Raya and ElevenLabs keys stay with your org, not in your requests.
Store one key per provider under Provider keys, or with PUT /v1/provider-keys/{provider} (see the REST API). The router uses it to call that provider for your org’s requests only. It’s stored encrypted and never returned, only its last four characters. Saving doesn’t check it with the provider: a wrong key surfaces as the provider’s refusal on your first request.
When a key is refused#
| Where | A missing, wrong or deleted API key gets |
|---|---|
| /v1/stream | HTTP 403 at the handshake. A key deleted while a connection is open: an unauthorized error at its next start. |
| /v1/audio/speech | HTTP 401, unauthorized. |
| /v1/provider-keys | HTTP 401, unauthenticated. |
| Sarvam drop-in | Sarvam's own refusal: HTTP 403 invalid_api_key_error, at the WebSocket handshake too. |
| Raya drop-in | Raya's own refusal: HTTP 401 Unauthorized. |
| ElevenLabs drop-in | ElevenLabs' own refusal: HTTP 400 invalid_api_key (401 with no key at all); on a WebSocket, that error message and close 1008. |
An org with no key stored for the provider gets provider_key_missing, or on the drop-ins the provider’s own refusal with a message that links to the dashboard. See Errors.