Authentication

The order and recording endpoints take an API key in the Authorization header. The trigger URL uses the secret token in its path instead.

Headers

Authorization: Bearer av_live_9a3f…
Content-Type: application/json

API keys

• A key looks like av_live_ followed by 16 to 128 letters, digits, _ or -.
• A key belongs to one workspace. It can create orders for any agent in that workspace and read that workspace's orders and recordings. There are no per-key scopes.
• A workspace can have more than one key, so you can rotate a key without downtime: add the new one, switch your systems, then revoke the old one.
• We store only a SHA-256 hash of the key, its first 12 characters and its last 4. A key is shown once, when it is created. If you lose it, make a new one.
• A revoked key stops working at once and gets 401 unauthorized.

Managing keys

Keys are managed in the dashboard under Developer. Every member of the workspace can see the list; only an owner or admin can create, rename or revoke a key.

• Create: pick Live (av_live_…) or Test (av_test_…) and give the key a name, such as the system that will use it. The full key is shown once. Copy it then; it cannot be shown again.
• List: each key shows its name, live or test, a hint such as av_live_9a3f…x7Qe (first 12 and last 4 characters), who made it, when, and when it was last used (updated at most once a minute). The full key is never shown again.
• Revoke: the key stops working on the next request (401 unauthorized). Revoking cannot be undone.
• A workspace can have at most 20 active keys. Revoke one to make room. At most 20 keys can be created per workspace per hour (429 rate_limited).
• Creating, renaming and revoking a key is recorded in the workspace audit log with who did it.

Test keys

A key that starts with av_test_ creates test orders. A test order never rings a phone, never sends a text, never holds or charges your wallet, and does not count toward your live-call limit. A simulated call plays out within about a minute and you get the normal signed webhooks, with "test": true in every payload.

• The request is checked exactly like a live one: consent is required, the number must be a US number, the agent must exist, be switched on and be published, and the do-not-contact list is checked. Only the wallet balance and the lead's calling hours are skipped.
• The reply to POST /v1/orders carries "test": true, and so does GET /v1/orders/{order_id}.
• Test webhooks never go to your production default webhook URL. They go to the order's webhook_url, else your workspace's test webhook URL (set by an owner or admin). With neither, nothing is sent.
• Billed minutes and charged cents are always 0.
• At most 500 test orders per workspace in any 24 hours; after that 429 rate_limited.
• An Idempotency-Key belongs to one mode: reusing a test order's key with a live key (or the reverse) is 409 idempotency_key_conflict, never the other order.

Pick the outcome with the last four digits of lead.phone:

For example +14155550002 plays the voicemail path. Use real US area codes (mainland, Alaska, Hawaii): a Canadian, Caribbean or US territory number is refused with 422 unsupported_destination, as in live mode.

When authentication fails

A missing, malformed, unknown or revoked key returns:

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": "unauthorized",
  "message": "A valid API key is required: Authorization: Bearer av_live_..."
}

Keeping keys safe

• Call the API from your server. The API answers browser CORS requests, but a key placed in web page code can be read by anyone.
• Keep keys in environment variables or a secrets manager, never in source control.
• Use a separate key per system (CRM, website, Zapier) so you can revoke one without breaking the others.

Trigger URL

The no-code trigger URL (/v1/hooks/lead/{token}) does not use an API key. The long random token in the URL is the credential. Treat the whole URL like a password. See Trigger URL.