Skip to content

Authentication & keys

Sending the key

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

x-api-key: vt_live_…

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 raj 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 ["anjura"] can only synthesise with Anjura: 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 itself uses an e-mail magic link (Google Identity Platform); there is no password to leak. 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.