Theme

Authentication ​

Use an API key for product requests, a user JWT for account management, and a short-lived ticket for browser WebSockets.

Choose a credential ​

  • Product API

    Developer API key

    Long-lived, scoped server credential for LLM, TTS, STT, Voice Isolator, Meeting AI, voices, and tickets.

  • Account API

    User access JWT

    Signed-in user credential for key management and analytics.

  • Realtime

    WebSocket ticket

    Short-lived credential for one browser or client connection.

Developer API key ​

Product endpoints use a long-lived API key:

http
Authorization: Bearer vlk_<your-secret>

Keep it in a server-side environment variable or secret manager:

bash
export VOICELAB_API_KEY=vlk_your_secret

API keys call /v1/tts, /v1/stt, /v1/voice-isolations, /v1/meetings, /v1/voices, history endpoints, and POST /v1/ticket. Permissions control which operations a key can perform.

For Voice Isolator, grant audio_isolation the access level to upload audio and poll or download results. Its compatibility scopes are audio_isolation:read and audio_isolation:write. Restricted keys need this permission explicitly; a write-only key can submit jobs but cannot poll them.

For Meeting AI, grant meetings the access level to upload recordings and poll results. Its compatibility scopes are meetings:read and meetings:write. Only personal workspace keys can use Meeting AI.

For LLM, grant llm the access level for model discovery, completions, and usage lookup. The compatibility scopes are llm:read and llm:write. These developer routes use /v1/models, /v1/chat/completions, and /v1/llm/requests/{id}. Ask's /api/v1/llm/* and /api/v1/chats/* routes use a platform JWT and remain uncharged.

User access JWT ​

Account key management and analytics under /api/v1/account/... require a signed-in user's access JWT:

http
Authorization: Bearer <USER_ACCESS_JWT>

Do not send a user JWT to /v1 product endpoints, and do not use a developer API key for account-management endpoints. The dashboard Voice Isolator routes at /api/v1/voice-isolations also require a user JWT; server integrations use /v1/voice-isolations with an API key.

Realtime WebSocket ticket ​

Never put a long-lived API key in a WebSocket URL. Use the API key to mint a short-lived ticket:

http
POST /v1/ticket
Authorization: Bearer vlk_...
Content-Type: application/json

{"transport":"websocket","service":"tts"}

Then connect with the returned ticket:

text
wss://api.voicelab.uz/v1/tts/stream?ticket=<short-lived-ticket>

Use "service":"stt" for /v1/stt/stream. Tickets expire after about two minutes.

Security checklist ​

  • Keep API keys out of frontend bundles, mobile apps, URLs, and logs.
  • Give each key only the permissions it needs.
  • Use allowed-IP restrictions where practical.
  • Use separate keys for production and staging.
  • Revoke an exposed key immediately.
  • Redact WebSocket query strings because they contain short-lived tickets.