VocenzaDocs

Authentication

Authenticate every request with a Bearer API key.

All requests require an API key. Create one from the Playground and send it in the Authorization header.

Authorization: Bearer voc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Creating a key

Open the Playground and click Create key. Copy the value immediately — it is shown once and stored only as a hash.

Keep secret keys server-side

Secret keys (voc_…) grant full access to your account. Never embed them in a browser, mobile app, or public repository. For client apps, mint short-lived ephemeral tokens from your backend instead.

Ephemeral tokens

For the Realtime API running in a browser, exchange your secret key for a short-lived token on your server and hand only that to the client.

server.ts
const r = await fetch("https://api.vocenza.com/v1/realtime/tokens", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOCENZA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ttl_seconds: 60 }),
});
 
const { token } = await r.json(); // pass `token` to the browser

Ephemeral tokens expire after ttl_seconds (default 60) and can only open realtime sessions — they cannot manage keys or billing.

Scoping

Each key belongs to a single project and inherits that project's plan, rate limits, and enabled models. Use separate projects for staging and production so a leaked staging key can't touch live traffic.

Rotation

Keys never expire on their own. To rotate, create a new key, deploy it, then revoke the old one from the Playground.