Getting started

Authentication

Two ways to authenticate against the Kotoba Realtime APIs.

All Kotoba Realtime APIs authenticate during the WebSocket handshake. There are two supported flows.

Send the API key as an HTTP Authorization: Bearer header on the handshake request. The Python SDK reads KOTOBA_API_KEY from the environment by default, or you can pass it explicitly:

1import kotoba
2
3client = kotoba.KotobaClient()                       # uses $KOTOBA_API_KEY
4# or
5client = kotoba.KotobaClient(api_key="kotoba-...")

Never embed long-lived API keys in browser-side code.

Browser / client-side

Browsers cannot set arbitrary headers on a WebSocket handshake. Instead:

  1. From your backend, mint a short-lived client secret by calling POST https://api.kotobatech.ai/v1/realtime/transcription_sessions.
  2. Pass the secret to the browser.
  3. The browser opens the WebSocket and supplies the secret through the Sec-WebSocket-Protocol header:
Sec-WebSocket-Protocol: realtime, kotoba-insecure-api-key.<CLIENT_SECRET>

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.