Authentication
The v1 public API authenticates with an API key, which identifies exactly one Organization. Keys are created in the app (Sviluppatori, then Accesso) and managed by an Owner or an Admin.
The header
Send the key in the Authorization header, with the Bearer scheme:
- Never put the key in the URL or in a query parameter.
- Always use HTTPS. A plain request gets
400 https_required. - The Organization comes only from the key: a parameter, header or body field that names another Organization is not followed.
- Authenticated responses carry
Cache-Control: no-store.
The key is a secret. Keep it on your servers, in a secret store or an environment variable: never in a browser, a mobile app, a repository or a log. Anyone who has it acts as your Organization within its scopes.
Key format
A key is vx_live_<prefix>_<secret> (live environment) or vx_test_<prefix>_<secret> (test environment). The visible prefix, for example vx_live_ab3k7x2q, is the only part the app shows you again.
A test key reads real data. Give test keys only the scopes they need and a short expiry, and revoke them when you no longer use them.
API version
The version is a date. Today only 2026-10-01 exists. Each key is pinned to the version that was current when it was created. The optional VoxAI-Version header overrides it for a single request; a version that does not exist is 400 invalid_api_version, with details.supported_versions. Every response reports the version used.
Scopes
Each route requires one scope, and no scope implies another. Give each key only the scopes it needs.
Two useful notes:
knowledge:searchis separate fromknowledge:read: the latter gives only document metadata, the former also their text.webhooks:managemanages endpoints but opens no data. To subscribe an endpoint to an event you also need the read scope of its family, for examplecalls:readforcall.ended. See Webhooks.
Two routes need no scope: GET /v1/openapi.json is public and GET /v1/me accepts any valid key.
Allowed addresses
You can restrict a key to a list of IP addresses (optional, at most 20 entries). Each entry is a single address or a network, IPv4 up to /16 or IPv6 up to /48. With an empty list the key works from any address. The list can be changed in the app without rotating the key.
Expiry and rotation
Every key has a mandatory expiry, from 1 to 730 days (365 by default).
To change a key without downtime, rotate it in the app:
- The app creates a new key with the same name, environment, scopes, addresses and version, and shows it only once.
- The old key keeps working for the overlap period, from 1 to 168 hours (24 by default).
- Update your systems with the new key before the overlap ends.
A key that was already rotated cannot be rotated again while its successor is active. Keys with the caller_requests:manage scope can be rotated only by an Owner.
Revocation
An Owner or an Admin can revoke any key in the app, giving a reason. Revocation is final and applies from the next request. If a key is compromised, revoke it at once and create a new one.
Authentication and access errors
401: invalid key
Missing, malformed, unknown, wrong secret, other environment, expired or revoked: the response is always the same, 401 invalid_api_key, with the header WWW-Authenticate: Bearer realm="VoxAI". On purpose, it does not say which case happened.
What to check: did you copy the whole key? Are you using the key of the right environment? Has it expired or been revoked? A token of the app’s users is not valid on v1.
403: the key is valid but not enough
These refusals come only after the secret is verified, so they can be told apart.
Example:
To fix insufficient_scope, create a key with the scope given: the scopes of an existing key do not change, and rotation keeps them.
Request limits
Each key has a limit of requests per minute, and another applies to all the Organization’s keys together. Responses report RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (in seconds) of the tighter counter. Over the limit the response is 429 rate_limited with Retry-After: wait that many seconds before retrying. GET /v1/me shows the limits in force for your key.
Wrong keys have a limit too: over 20 failures per minute from the same address, requests get 429 rate_limited before the key is even checked.