Kotoba Authentication

generated: '2026-07-19'
method: searched
source: openapi/kotoba-asr-realtime-openapi-original.yml, openapi/kotoba-sts-realtime-openapi-original.yml,
  openapi/kotoba-tts-realtime-openapi-original.yml
docs: https://docs.kotoba.tech/overview/authentication
notes: >-
  Derived from the published securitySchemes, then upgraded from the docs auth
  page. All Kotoba realtime APIs authenticate during the WebSocket handshake.
  The docs describe a third, browser-oriented flow that is NOT expressed in any
  published spec: mint a short-lived client secret server-side and pass it via
  the Sec-WebSocket-Protocol subprotocol header. There is no OAuth 2.0 or OIDC
  surface — `scopes/` is intentionally absent for this provider.
summary:
  types:
  - http
  - client-secret
  api_key_in: [header]
  oauth2_flows: []
  oauth2: false
  openid_connect: false
schemes:
- name: bearerAuth
  type: http
  scheme: bearer
  description: |-
    HTTP Bearer authentication. Pass the Kotoba API key as a Bearer
    token via the Authorization header. Server-side use only.
  sources:
  - openapi/kotoba-asr-realtime-openapi-original.yml
  - openapi/kotoba-tts-realtime-openapi-original.yml
- name: httpBasic
  type: http
  scheme: basic
  description: |-
    HTTP Basic authentication. Set device_id as the username and api_key
    as the password. Send it via the Authorization header during the
    WebSocket handshake.
  sources:
  - openapi/kotoba-sts-realtime-openapi-original.yml
- name: browserClientSecret
  type: client-secret
  in: header
  parameter: Sec-WebSocket-Protocol
  format: 'realtime, kotoba-insecure-api-key.<CLIENT_SECRET>'
  description: |-
    Browser / client-side flow. Browsers cannot set arbitrary headers on a
    WebSocket handshake, so the backend mints a short-lived client secret by
    calling POST https://api.kotobatech.ai/v1/realtime/transcription_sessions,
    passes it to the browser, and the browser supplies it through the
    Sec-WebSocket-Protocol header. Documented but not present in any published
    spec. No browser-side SDK is available yet.
  mint_endpoint: https://api.kotobatech.ai/v1/realtime/transcription_sessions
  short_lived: true
  sources:
  - https://docs.kotoba.tech/overview/authentication
guidance:
  server_side_recommended: true
  warning: Never embed long-lived API keys in browser-side code.
  env_var: KOTOBA_API_KEY
  sdk: kotoba-sdk (Python) reads KOTOBA_API_KEY from the environment by default