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
remember_me & refresh tokens
Whenremember_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).
Magic link (passwordless)
Users can also authenticate without a password via a magic link sent to their email.POST /api/auth/request-magic-link— sends the linkPOST /api/auth/validate-magic-link— exchanges the token in the link for a JWT
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_codeswith 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:- Redirect the user to the provider’s authorisation URL
- Provider redirects back with an authorisation code
- The API exchanges the code for an access token and returns a Kair Voice JWT
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
User API keys
Users with rolemoderator 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 Unauthorizedon 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 theX-API-Key header:
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
Onlymoderator 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}/heartbeatPOST /api/devices/{device_id}/session/startPOST /api/devices/{device_id}/session/stopPOST /api/sessions/{session_id}/upload-audio
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/loginPOST /api/auth/guestPOST /api/devices/pairing-codes(device publishes pairing code)GET /api/devices/pair/status(device polls pairing status)GET /api/health