Skip to navigation

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:

curl https://api.getvoxai.com/v1/me \
-H "Authorization: Bearer vx_live_ab3k7x2q_…"
  • 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.

EnvironmentPrefixBehavior
Livevx_live_Real reads and writes. Operations that cost (calls, campaigns, indexing) use minutes.
Testvx_test_Reads return the Organization’s real data. Writes are simulated: every check runs, then nothing is done and nothing is billed.

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.

ScopeWhat it allows
calls:readRead calls: list, transcripts, Report card and collected data.
calls:startStart outbound calls to a number with an Agent.
campaigns:readRead outbound campaigns, their contacts and the outcome of each contact.
campaigns:writeCreate campaigns, upload contacts, start and pause campaigns.
knowledge:readRead the documents of the Knowledge base and the state of their indexing.
knowledge:searchSearch the Knowledge base and read passages of its documents, which can contain confidential or personal data.
knowledge:writeUpload, update and delete Knowledge base documents.
agents:readRead Agents, without the details of their internal configuration.
agents:operateManage Agents within safe limits: variables, Schedules, closures, suspension and resumption.
usage:readRead the usage of the period, the limits and the concurrent calls.
lines:readRead the phone Lines.
widget:sessionIssue session tokens for the widget on the Organization’s website.
caller_requests:manageSearch, export and erase a caller’s data by phone number, and record their objection to being called. Only an Owner can grant it.
webhooks:manageManage webhook endpoints, events and deliveries.

Two useful notes:

  • knowledge:search is separate from knowledge:read: the latter gives only document metadata, the former also their text.
  • webhooks:manage manages endpoints but opens no data. To subscribe an endpoint to an event you also need the read scope of its family, for example calls:read for call.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:

  1. The app creates a new key with the same name, environment, scopes, addresses and version, and shows it only once.
  2. The old key keeps working for the overlap period, from 1 to 168 hours (24 by default).
  3. 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.

{
"error": "Invalid or missing API key.",
"code": "invalid_api_key",
"requestId": "…"
}

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.

CodeMeaning
insufficient_scopeThe key lacks the route’s scope. details.required_scope says which one is needed.
ip_not_allowedThe source address is not in the key’s list.
organization_suspendedThe Organization is suspended or closed.
feature_not_availableA feature is not included in the plan: the public API, or webhooks for their writes. details.feature says which.
not_available_in_test_modeThe operation cannot run with a test key.

Example:

{
"error": "This API key does not have the scope required for this operation.",
"code": "insufficient_scope",
"details": { "required_scope": "calls:read" },
"requestId": "…"
}

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.

Glossary

TermMeaning
OrganizationYour company’s account on VoxAI. Every key, call and resource belongs to one Organization.
Owner, Admin, MemberThe roles of the app’s users. Only Owners and Admins manage keys.
AgentA voice agent: answers calls on a Line or calls out.
LineA phone number of the Organization.
Report cardThe evaluation of a call: outcome and collected data.
Knowledge baseThe documents an Agent uses to answer.
Caller requestsThe register of requests from callers about their data (access, erasure, objection).