Authentication

PreviousNext

API key, session token, and browser-side security.

Lanson Live API requests require authentication. This page explains how to get an API key through Lanson Live App, use it on your server, and issue short-lived tokens for browsers.

Get an API key

  1. Sign in to Lanson Live App, or create a free account.
  2. Open the API Key Console (Live → Account → Developer).
  3. Click Create API key, optionally add a label, and copy the sk-... key when it appears.

New API developer accounts include $5 of free credit. Usage is charged in USD; you can top up from the same Developer panel.

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. For a quick auth check, issue a session token:

curl -X POST -H "Authorization: Bearer sk-..." \
  https://audio.lansonai.com/v1/audio/transcriptions/session-token

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:

Session Token Exchange Flow

  1. Frontend → Backend: Request a short-lived session token.
  2. Backend → LansonAI: Call POST /v1/audio/transcriptions/session-token with Authorization: Bearer sk-... (long-lived key, server-side only).
  3. LansonAI → Backend: Returns an ephemeral rt_... token (valid for 60 seconds).
  4. Backend → Frontend: Return the rt_... token to the client.
  5. Frontend → LansonAI: Open WebSocket connection directly using ?access_token=rt_....

Session token details

PropertyValue
Prefixrt_
Validity60 seconds
SignatureHMAC-SHA256
Signing secretGATEWAY_SESSION_TOKEN_SECRET (server-side config)
TransportURL 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:

MethodUse caseUsage
Authorization: Bearer sk-...Server-side clientsHTTP upgrade header
?access_token=rt_...BrowserURL query parameter
?token=rt_...BrowserURL query parameter (alias)

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 codeHTTPCause
missing_api_key401No Authorization header or query token
invalid_api_key401Key format invalid or unknown key
revoked_api_key401Key has been revoked
expired_api_key401Key has expired
auth_unavailable503Key store unavailable
invalid_session_token401Session token invalid or expired
token_issuer_unavailable503Token issuer not configured

See Errors for the full error reference.

Next steps