> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kotoba.tech/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kotoba.tech/_mcp/server.

# Authentication

All Kotoba Realtime APIs authenticate during the WebSocket handshake.
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 reads `KOTOBA_API_KEY` from the
environment by default, or you can pass it explicitly:

```python
import kotoba

client = kotoba.KotobaClient()                       # uses $KOTOBA_API_KEY
# or
client = kotoba.KotobaClient(api_key="kotoba-...")
```

> **Warning**
>
> 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.