Getting started

Authentication

One key, one header, one organization. Everything else is about narrowing what that key can do.

Sending the key

Every request carries the key as a bearer token. Keys are created and revoked under Settings → API Keys, and a revoked key stops working immediately rather than at the end of a session.

curl "https://vocalis.io/api/v1/calls" \
  -H "Authorization: Bearer $VOCALIS_API_KEY"

x-api-key still works

The original public API took the key in an x-api-key header and existing integrations are not expected to move. New code should use the bearer form.

What a key is

dk_…: Keys are prefixed so they can be recognised in a log or a leak scan. The rest is random and is shown once, at creation.
one organization: A key belongs to the organization you were working in when you made it, even if your own account belongs to several. A resource in another organization answers 404, the same as one that does not exist.
your permissions, or less: By default a key can do whatever you can do in that organization. Listing scopes at creation narrows it, and it can never be widened past what you hold.

Treat a key as a password

Keep it in an environment variable or a secret store. Never in source control, a browser bundle, or a mobile app.

Scopes

Scopes are capability names in resource:action form. Name them when you create a key and it can do only those things, worth doing for anything that lives in a script, a partner integration, or anywhere the blast radius matters more than convenience.

POST /settings/api-keys

{
  "name": "Reporting export",
  "scopes": ["call:read", "campaign:read"]
}

Each endpoint's reference page names the capability it requires. A request outside a key's scopes is refused with 403 INSUFFICIENT_SCOPE, and the refusal names the capability that was missing.

Reading a call and listening to its recording are separate capabilities. A transcript redacts what the audio does not, so call:read does not include call:listen.

When it fails

401INVALID_API_KEY: No key on the request, or one that does not exist.Check the header name and that the variable is actually set in the environment the code is running in.
401EXPIRED_API_KEY: The key was revoked or has passed its expiry.Create a new one and rotate it in.
403INSUFFICIENT_SCOPE: A valid key, refused for this endpoint. The message names the capability it wanted.Scopes are fixed at creation, issue a new key rather than editing this one.
429RATE_LIMIT_EXCEEDED: 60 requests a minute, 10,000 a day, counted per key.Back off and retry; see rate limits.