Skip to main content

Overview

The API uses two authentication mechanisms depending on who is making the request:

User authentication (JWT)

Users log in via the web app. On successful login the API returns a signed JWT. The web app stores this and sends it with every subsequent request. Login endpoint: POST /api/auth/login
Returns:

remember_me & refresh tokens

When remember_me: true is passed, the API issues a refresh token alongside the access token. The refresh token lives for 12 hours. Use it to get a new access token without re-entering credentials: Refresh endpoint: GET /api/auth/refresh-token Send the refresh token as a bearer token. Returns a fresh access token. Without remember_me, the session ends when the browser tab closes (no refresh token issued). Users can also authenticate without a password via a magic link sent to their email.
  1. POST /api/auth/request-magic-link — sends the link
  2. POST /api/auth/validate-magic-link — exchanges the token in the link for a JWT
Magic-link sessions are single-factor (mfa: false). Passkey sign-in with user verification sets mfa: true; platform admins need that to use /admin (see Admin MFA).

Step-up authentication

Sensitive actions (data export, erasure requests) require a JWT issued within the last 10 minutes (auth_time claim). When the user’s token is older than that, the API returns 403 Fresh authentication required. Rather than forcing a full re-login, the web app prompts for a 6-digit email OTP:

Request a code

  • Requires a valid (but not necessarily fresh) JWT.
  • Generates a random 6-digit code, stores a SHA-256 hash in step_up_codes with a 15-minute TTL.
  • Emails the code to the user’s registered address.
  • Rate-limited: 3 requests per hour per user.
  • Debug builds: code is logged via tracing::info! instead of emailed.

Verify the code

  • Finds the most-recent unexpired, unused code for the user and verifies the hash.
  • On success: marks the code used, issues a new JWT with auth_time = now(), returns { "access_token": "..." }.
  • On failure: returns 400 Invalid or expired code.
  • Rate-limited: 10 attempts per 10 minutes per user.

OAuth2

The web app supports OAuth2 for third-party identity providers. The OAuth2 flow follows the standard authorisation code pattern:
  1. Redirect the user to the provider’s authorisation URL
  2. Provider redirects back with an authorisation code
  3. The API exchanges the code for an access token and returns a Kair Voice JWT
OAuth2 providers are configured server-side; contact an admin to enable a provider for your workspace.

Guest access

Participants joining a session without an account receive a guest token scoped to that session only. Guest login endpoint: POST /api/auth/guest
Guest tokens can access the session they were issued for, nothing else.

User API keys

Users with role moderator or admin can create long-lived API keys for programmatic access. Participants cannot create API keys.

Creating a key

Endpoint: POST /api/api-keys
The response includes the raw key once — it is not stored and cannot be retrieved again:

Workspace scoping

A key can be scoped to all workspaces (default, workspace_id: null) or a specific workspace (workspace_id: <uuid>).
  • An all-workspaces key can access any workspace the user is a member or owner of.
  • A specific-workspace key is rejected with 401 Unauthorized on any request that targets a different workspace. The user must be either the workspace owner or a junction-table member of the named workspace at key-creation time.

Using a key

Send the key in the X-API-Key header:
The key authenticates as the user who created it, subject to their role and the workspace scope. Chunked uploads that omit Content-Length (for example streaming multipart bodies from a third-party client using an API key) receive 411 Length Required on size-limited upload routes before the handler runs.

Managing keys

Role restriction

Only moderator and admin users can create API keys. Participants receive 401 Unauthorized. This is enforced server-side regardless of the UI.

Device authentication (API key)

Physical devices authenticate with a device-scoped API key obtained during the pairing flow. See Devices for the full pairing process. Protected device endpoints:
  • POST /api/devices/{device_id}/heartbeat
  • POST /api/devices/{device_id}/session/start
  • POST /api/devices/{device_id}/session/stop
  • POST /api/sessions/{session_id}/upload-audio
Device API keys last 30 days (devices.api_key_expiry_hours, independent of web JWT auth.token_expiry_hours). After expiry the device must pair again to mint a new key.

Roles

Endpoints that don’t require authentication

  • POST /api/auth/login
  • POST /api/auth/guest
  • POST /api/devices/pairing-codes (device publishes pairing code)
  • GET /api/devices/pair/status (device polls pairing status)
  • GET /api/health