Authentication
All API requests require an API key. This page explains the key format, usage patterns, and browser-side security model.
API key format
- Prefix:
sk- - The plaintext key is returned only once at provisioning. The server stores only a SHA-256 hash.
- Minimum length: 16 characters (at least 13 characters after
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
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) |
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.
Next steps
- Quickstart — first request
- Errors — full error reference
- Realtime API — WebSocket endpoint details