Authentication & keys

Sending the key

Every /v1 request needs a key, in either header form:

request.http

x-api-key: vt_live_…

request.http

Authorization: Bearer vt_live_…

WebSocket handshakes from browsers cannot carry headers, so WS /v1/tts/stream also accepts ?api_key=vt_live_… on the URL. Don't put long-lived keys in browser code: mint short-lived ones from your back end (the portal's playground does exactly this with vt_pg_… tokens that expire after two hours).

Situation	Response
No key	401 {"error":"missing x-api-key"}
Unknown or revoked key	401 {"error":"invalid api key"}
Voice not in the key's allow-list	403 {"error":"voice sahil not allowed for this key"}

Keys, projects and organisations

• An organisation is the billing boundary: one invoice, one member list. You get one on first sign-in; invite colleagues by e-mail under Settings. Roles: owner (settings, members) and member (keys, playground, usage).
• A project groups keys and attributes usage (e.g. production, staging, ivr). Every organisation starts with Default.
• An API key belongs to a project. It has a name, an optional voice allow-list, a creation date and a last-used time. Keys are stored hashed; the portal shows the full value once, at creation.

Limits: 50 active keys per organisation. Revocation is immediate (the next request gets 401).

Voice allow-lists

A key created with voices ["saanvi"] can only synthesise with Saanvi: any other voice is 403, and GET /v1/voices returns only the voices it may use. A key with ["*"] may use every voice, including ones added later. Use per-voice keys to hand a partner one voice, or to make sure an IVR deployment never accidentally switches voice.

Rotation

Create the new key, deploy it, confirm traffic under Usage → By key, then revoke the old one. Both work in the meantime.

Playground keys

vt_pg_… keys are issued to the signed-in portal session for the current project, live two hours, allow every voice, and show up in usage as playground. They are the pattern we recommend for your own browser clients: have your server exchange a user session for a short-lived key.

Portal sign-in

The portal at tts.vartalaap.si signs you in with e-mail and password (with e-mail verification and password reset) or with Continue with Google, both on Google Identity Platform. Sign-up at tts.vartalaap.si/signup asks for your name, company, phone (optional), use case and expected volume. Magic links are no longer sent; ones already in your inbox still work. Portal calls carry a short-lived ID token, never your API keys. Programmatic key management is available through the portal API with the same token.