Vocatech

Start

Keys and access

Written beside the API’s code, and read from it every hour.

Plain text

Every request carries a key in the Authorization header.

Header
Authorization: Bearer YOUR_API_KEY

A key is an opaque secret of 48 characters, or 32 on an older key. It is not a JWT, and there is nothing inside it to read. Keep it on your server, in an environment variable or a secret store, and out of logs, URLs and code.

No key, a wrong key, or a key that was turned off or regenerated gets 401. If the API cannot check a key for a moment, it answers 503 with Retry-After: 5. That is not a revoked key. Wait a few seconds and try again.

Response401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Invalid token or inactive user."
}

Keys and their access

Keys are made in the portal, on the Integrations page under API keys. An account holds up to 10 keys in use, one for each system or integrator, each with its own name. The API itself cannot create or change keys.

Every key carries an access setting.

AccessReaches
Full accessEvery route, calls, texts, faxes, contacts, webhooks and the AI Agent
TextingSending and reading texts, their pictures, and the text events on a webhook (the messaging scope)
CallsCalls with their recordings, summaries and transcripts, the contacts, and the call events on a webhook (the calls scope)
AI AgentYour AI agents, the calls they place for you, and who a caller is (the agents scope)

A key holds Full access, or any of the other three together. Give each system the least it needs. A key that can text is also listed under Textdock, API Messaging, with the month's usage and a tester. For a help desk or a chat bot, ask Vocatech support for a key narrowed to support or knowledge.

Texting is the same on every key

Any key that can text sends the same way. A whole batch is accepted and paced out by a queue at 60 message parts a minute. Each outgoing part costs $0.02, and replies are free. Texts sent through the API are paid texting, so the account's included texting limit, which is for the texts its people send, never holds them back and they never use it up. A key locked to fixed addresses sends up to 5,000 texts a day. A key that works from any address sends up to 500 a day.

Scopes

A key with Full access carries no scope and reaches every route. A limited key reaches only the routes of its scopes. Any key may call GET /v1/whoami.

ScopeReachesNotes
messaging/v1/messages (send, history, queue), /v1/reports/messages, /v1/media, /v1/webhooksMedia means message attachments only, never recordings or faxes. Webhooks means the three message events, on endpoints this key created.
calls/v1/calls, /v1/reports/calls, /v1/contacts, /v1/media, /v1/webhooksMedia means call recordings only, never attachments or faxes. Webhooks means the four call events, on endpoints this key created. It does not reach /v1/callers, whose answer carries a number's texts.
agents/v1/agents, /v1/callers, /v1/contacts/lookup, /v1/webhooks (the agent.call.* events)What an AI agent needs, who is calling, your agents and the calls they place for you.
support/v1/support, /v1/knowledgeOpen tickets and ask the knowledge base.
knowledge/v1/knowledgeAsk the knowledge base, nothing else.

Outside its scope, a key gets 403.

Response403 Forbidden
{
  "error": "Forbidden",
  "message": "This API key is limited to messaging and cannot be used for /v1/calls.",
  "scopes": "messaging",
  "path": "/v1/calls"
}

IP allow-list

Lock a key to the addresses your servers call from, and a copied key is useless anywhere else.

  • Enter exact IPv4 or IPv6 addresses. Ranges are not accepted. An empty list means any address.
  • The list is optional on every key. In the portal, tick Lock this key to fixed IP addresses on the key and enter the addresses.
  • A key with a list sends up to 5,000 texts a day. A key with no list sends up to 500 a day.

Before you lock a key, call GET /v1/whoami from the server that will use it and allow the client_ip it reports. The Connections panel next to the key lists every address the key was called from. Matching is exact. An IPv4 address and its IPv6 form (::ffff:203.0.113.24) count as two different addresses.

A request from any other address gets 403. The answer names the address the API saw, so when calls that worked start failing, you can see at once that your server's address changed.

Response403 Forbidden
{
  "error": "Forbidden",
  "message": "This API key is restricted to specific IP addresses and 203.0.113.24 is not one of them.",
  "client_ip": "203.0.113.24"
}

Rotating a key

Press Regenerate next to the key and confirm. The new key replaces the old one at once, and from that moment the old key gets 401. So rotate in this order.

  1. Make sure your system can take a new key quickly, from a secret store or an environment variable.
  2. Regenerate in the portal and copy the new key.
  3. Put it in place and restart whatever reads it.

Each key regenerates on its own, and no other key on the account is touched. If a key leaks, regenerate it right away and tell us.