> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# 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:

```bash
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`.

> **Warning**
>
> 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.

| Environment | Prefix     | Behavior                                                                                                                       |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Live        | `vx_live_` | Real reads and writes. Operations that cost (calls, campaigns, indexing) use minutes.                                          |
| Test        | `vx_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.

| Scope                    | What it allows                                                                                                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `calls:read`             | Read calls: list, transcripts, Report card and collected data.                                                                    |
| `calls:start`            | Start outbound calls to a number with an Agent.                                                                                   |
| `campaigns:read`         | Read outbound campaigns, their contacts and the outcome of each contact.                                                          |
| `campaigns:write`        | Create campaigns, upload contacts, start and pause campaigns.                                                                     |
| `knowledge:read`         | Read the documents of the Knowledge base and the state of their indexing.                                                         |
| `knowledge:search`       | Search the Knowledge base and read passages of its documents, which can contain confidential or personal data.                    |
| `knowledge:write`        | Upload, update and delete Knowledge base documents.                                                                               |
| `agents:read`            | Read Agents, without the details of their internal configuration.                                                                 |
| `agents:operate`         | Manage Agents within safe limits: variables, Schedules, closures, suspension and resumption.                                      |
| `usage:read`             | Read the usage of the period, the limits and the concurrent calls.                                                                |
| `lines:read`             | Read the phone Lines.                                                                                                             |
| `widget:session`         | Issue session tokens for the widget on the Organization's website.                                                                |
| `caller_requests:manage` | Search, export and erase a caller's data by phone number, and record their objection to being called. Only an Owner can grant it. |
| `webhooks:manage`        | Manage 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](/concepts/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.

```json
{
  "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.

| Code                         | Meaning                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `insufficient_scope`         | The key lacks the route's scope. `details.required_scope` says which one is needed.                                |
| `ip_not_allowed`             | The source address is not in the key's list.                                                                       |
| `organization_suspended`     | The Organization is suspended or closed.                                                                           |
| `feature_not_available`      | A feature is not included in the plan: the public API, or webhooks for their writes. `details.feature` says which. |
| `not_available_in_test_mode` | The operation cannot run with a test key.                                                                          |

Example:

```json
{
  "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

| Term                 | Meaning                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------ |
| Organization         | Your company's account on VoxAI. Every key, call and resource belongs to one Organization. |
| Owner, Admin, Member | The roles of the app's users. Only Owners and Admins manage keys.                          |
| Agent                | A voice agent: answers calls on a Line or calls out.                                       |
| Line                 | A phone number of the Organization.                                                        |
| Report card          | The evaluation of a call: outcome and collected data.                                      |
| Knowledge base       | The documents an Agent uses to answer.                                                     |
| Caller requests      | The register of requests from callers about their data (access, erasure, objection).       |