Authentication

Integrations authenticate to the VOIX APIs with an API key. Keys are created by an admin under Organisation → API and belong to one workspace. The full key is shown once, when it is created; store it in a secret manager.

API keys are for server-to-server use, such as your phone system or a data sync. To act as a VOIX user, for example from an AI assistant or an app each user connects to their own account, use OAuth instead.

Sending the key

Pass the key as a bearer token on every request:


Authorization: Bearer vx_your_api_key

Permission

Each key has one of two permissions, chosen when it is created:

Permission	Allows
Full access	Everything: `POST /v1/submit` on the Ingest API, every `GET` on the REST API, and creating and changing lenses, checks and topics.
Sending access	Only `POST /v1/submit`: sending calls to VOIX. It cannot read data or change settings.

Give your phone system a Sending access key. Use Full access only for your own integrations that read results or manage lenses, checks and topics, such as a reporting or CRM sync. If a sending key leaks, it can add calls but cannot read any.

Scopes

Under the hood a permission is a set of scopes: Full access is ingest, read and manage; Sending access is ingest. Keys created before permissions existed may have a different set; they keep working and show as Custom in the dashboard.

Organisation and team keys

Whatever its permission, a key belongs either to the whole organisation or to one team.

Organisation keys send calls for any team: pass the teamId the call belongs to. With Full access they also read data across the organisation and manage organisation-wide lenses, checks and topics.
Team keys only send calls into their own team; a different teamId returns 403. With Full access they read the same data and manage only their own team’s lenses and checks. Topics are organisation-wide and need an organisation key.

Errors

Code	Meaning
`401`	The key is missing, unknown, revoked or expired.
`403`	The key is valid but lacks the permission this request needs (for example a sending key reading data), or is a team key acting outside its team.

See Errors for the full list.