Authentication
All API requests require an API key. This page explains the key format, usage patterns, and browser-side security model.
API key format
sk-sk-)Server-side usage
All endpoints accept the key via the Authorization: Bearer header:
curl -H "Authorization: Bearer sk-..." https://audio.lansonai.com/v1/audio/transcriptions
This works for both offline HTTP requests and WebSocket upgrade handshakes.
Browser-side security
::callout{icon="i-lucide-circle-alert" color="red"} Never expose your long-lived API key in frontend code or WebSocket URLs. Use a short-lived session token for browser connections. ::
Session token flow
Browsers cannot safely store a long-lived key. LansonAI provides a short-lived token mechanism:
1. Frontend → your backend: request a session token
2. Your backend → LansonAI:
POST /v1/audio/transcriptions/session-token
Authorization: Bearer sk-... (your long-lived key, server-side only)
3. LansonAI → your backend: returns rt_... token (valid 60 seconds)
4. Your backend → frontend: pass the rt_... token
5. Frontend → LansonAI: open WebSocket
?access_token=rt_...
Session token details
| Property | Value |
|---|---|
| Prefix | rt_ |
| Validity | 60 seconds |
| Signature | HMAC-SHA256 |
| Signing secret | GATEWAY_SESSION_TOKEN_SECRET (server-side config) |
| Transport | URL query ?access_token=rt_... or ?token=rt_... |
Token response
{
"token": "rt_eyJ...",
"expires_in": 60,
"endpoint": "/v1/audio/transcriptions/stream"
}
If GATEWAY_SESSION_TOKEN_SECRET is not configured, the endpoint returns 503 token_issuer_unavailable.
WebSocket authentication methods
The realtime WebSocket accepts three authentication methods:
| Method | Use case | Usage |
|---|---|---|
Authorization: Bearer sk-... | Server-side clients | HTTP upgrade header |
?access_token=rt_... | Browser | URL query parameter |
?token=rt_... | Browser | URL query parameter (alias) |
::callout{icon="i-lucide-triangle-alert" color="amber"}
Never put sk-... in a URL. Browser connections must always use rt_... session tokens.
::
Admin API
Key provisioning, revocation, and plan-catalog endpoints exist under /v1/external-transcription, but they are for internal operators and dashboards, not regular API consumers. See Admin API for details.
Error handling
| Error code | HTTP | Cause |
|---|---|---|
missing_api_key | 401 | No Authorization header or query token |
invalid_api_key | 401 | Key format invalid or unknown key |
revoked_api_key | 401 | Key has been revoked |
expired_api_key | 401 | Key has expired |
auth_unavailable | 503 | Key store unavailable |
invalid_session_token | 401 | Session token invalid or expired |
token_issuer_unavailable | 503 | Token issuer not configured |
See Errors for the full error reference.