Getting started
Authentication
API keys
Create keys in the Voximate dashboard under Settings → API keys. Each key has a name, the scopes you pick, and an optional expiry date. The key itself — vox_live_ followed by a long random string — is shown once, when you create it. Voximate stores only a hash of it, so a lost key cannot be recovered: create a new one and revoke the old.
Workspace owners and admins create and revoke keys, and only a key made by an owner or admin can add, change, test or remove a webhook endpoint (403 role_required otherwise): a key and a webhook both open your call data to another system.
Sending the key
Send the key as a bearer token on every request. There is no other way to authenticate: no query parameter and no cookie.
curl https://api.voximate.no/public/v1/agents \
-H "Authorization: Bearer vox_live_…"Scopes
A scope is one permission. Give each key only the scopes its system needs: a reporting job needs calls:read, not calls:write. A write scope includes its read: a key with calls:write can also list and read calls. GET /me needs no scope, so any valid key can call it.
| Scope | Allows | Endpoints |
|---|---|---|
| agents:read | Read agents and their settings. | GET /agentsGET /agents/{agent_id} |
| agents:write | Create, change, publish, unpublish and delete agents. | POST /agentsPATCH /agents/{agent_id}DELETE /agents/{agent_id}POST /agents/{agent_id}/publishPOST /agents/{agent_id}/unpublish |
| calls:read | Read calls, their analysis and transcripts. | GET /callsGET /calls/{call_id}GET /calls/{call_id}/transcript |
| calls:write | Start outbound calls. Each one rings a real phone. | POST /calls |
| numbers:read | Read your phone numbers and which agent answers each. | GET /phone-numbersGET /phone-numbers/{phone_number_id} |
| numbers:write | Assign agents to phone numbers. | PATCH /phone-numbers/{phone_number_id} |
| webhooks:read | Read webhook endpoints and their delivery log. | GET /webhooksGET /webhooks/{webhook_id}GET /webhooks/{webhook_id}/deliveries |
| webhooks:write | Create, change, test and delete webhook endpoints, and rotate their secrets. | POST /webhooksPATCH /webhooks/{webhook_id}DELETE /webhooks/{webhook_id}POST /webhooks/{webhook_id}/testPOST /webhooks/{webhook_id}/rotate-secret |
| analytics:read | Read usage: calls and minutes for a period. | GET /usage |
Keys and roles
A key acts as the person who created it, with their role in the workspace. If that person could not do something in the dashboard, their key cannot do it through the API either — whatever its scopes say. When someone leaves your company, revoke the keys they created.
401 and 403
401authentication_error— no key was sent, or the key is wrong, expired or revoked. Revoking a key takes effect within 60 seconds.403permission_errorwith codemissing_scope— the key is valid but lacks the scope this endpoint needs. The message names the scope. Create a key with that scope; scopes on an existing key cannot be changed.
{
"error": {
"type": "permission_error",
"code": "missing_scope",
"message": "This API key needs the calls:write scope.",
"param": null
},
"request_id": "req_8f14e45fceea167a"
}Keeping keys safe
- Keep keys on your server, in an environment variable or a secret manager. Never in a browser, an app or a repository.
- One key per system, so revoking one breaks nothing else.
- Set an expiry date on keys for short projects and contractors.
- If a key leaks, revoke it in the dashboard at once. It stops working within a minute.