Authentication
All Kotoba Realtime APIs authenticate during the WebSocket handshake, and the REST transcription endpoint uses the same header. There are two supported flows.
Server-side (recommended)
Send the API key as an HTTP Authorization: Bearer header on the
handshake request. The Python SDK adds the header for you and picks the
auth scheme from the endpoint host automatically, so the same
KOTOBA_API_KEY works against any deployment the SDK supports. It reads
KOTOBA_API_KEY from the environment by default, or you can pass it
explicitly:
Never embed long-lived API keys in browser-side code.
Browser / client-side
Browsers cannot set arbitrary headers on a WebSocket handshake. Instead:
- From your backend, mint a short-lived client secret by calling
POST https://api.kotobatech.ai/v1/realtime/transcription_sessions. - Pass the secret to the browser.
- The browser opens the WebSocket and supplies the secret through the
Sec-WebSocket-Protocolheader:
A browser-side SDK that handles this automatically is not yet available.
For now, drive the WebSocket directly from the browser using the
Sec-WebSocket-Protocol flow described above.