Start
.md ↗

Authentication

Bearer keys, where to keep them, and how to correlate requests when something goes wrong.

Every REST /v1/* endpoint authenticates with an API key. Send it as a bearer token (preferred):

bash
curl -s https://api.kalpalabs.ai/v1/models \
  -H "Authorization: Bearer $KALPA_API_KEY"

or, where headers are awkward to compose, as X-API-Key:

bash
curl -s https://api.kalpalabs.ai/v1/models -H "X-API-Key: $KALPA_API_KEY"

The WebSocket API is the exception: send the key in the first initializeConnection message.

A missing or invalid key returns 401 in the standard envelope:

json
{ "error": { "type": "authentication_error", "message": "Invalid API key.", "request_id": "…" } }

If key verification is temporarily unavailable on our side, you get 503 with type service_unavailable — retry with the same key; do not treat it as an invalid key.

Keys

  • Keys are provisioned per team while the API is in early access — write to hello@kalpalabs.ai to get one, rotate one, or raise its limits.
  • Each key carries its own rate limits and its own usage meter.
  • Treat the key like a password: call the API from your servers, not from browsers or shipped apps. If a key leaks, ask us to rotate it.

Request IDs

Every HTTP response carries an X-Request-ID header, echoed into error envelopes and our logs. Successful /v1/tts and /v1/converse bodies also return the same value as request_id. Pass your own X-Request-ID header to correlate with your systems, and include the id when reporting a problem.