Start
Keys and access
Written beside the API’s code, and read from it every hour.
Every request carries a key in the Authorization header:
Authorization: Bearer YOUR_API_KEYA key is an opaque 32-character secret. 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.
{
"error": "Unauthorized",
"message": "Invalid token or inactive user."
}Main and API Messaging keys
The portal makes two kinds of key. The API itself cannot create or change keys.
| Property | Main key | API Messaging keys |
|---|---|---|
| Made in | Integrations page, Portal Public API, Generate | Textdock, API Messaging |
| How many | One per account | Up to 10 per account: one for each integrator, each with its own label |
| Reaches | Every route | Texting only (the messaging scope) |
| Sending texts | Up to 20 a minute and 200 a day through POST /v1/messages, inside the account's included texting (50 texts an hour and 150 a day as standard, shared with the texts the account's people send) | A whole batch is accepted and paced out by a queue, 60 message parts a minute and 5,000 messages a day to start, set per key. Paid per message, so the account's included texting limit never holds these back and they never use it up |
| IP allow-list | Optional | Required |
API Messaging keys are metered. A key can also be narrowed to agents, support or knowledge, for an AI agent, a help desk or a chat bot that should reach nothing else. Ask Vocatech support for one.
Scopes
A key with no scope reaches every route. A narrowed key reaches only the routes of its scopes. Any key may call GET /v1/whoami.
| Scope | Reaches | Notes |
|---|---|---|
messaging | /v1/messages (send, history, queue), /v1/reports/messages, /v1/media, /v1/webhooks | Media: message attachments only, never recordings or faxes. Webhooks: the three message events, on endpoints this key created. |
agents | /v1/agents, /v1/callers, /v1/contacts/lookup | What an AI agent needs: who is calling, and your agents. |
support | /v1/support, /v1/knowledge | Open tickets and ask the knowledge base. |
knowledge | /v1/knowledge | Ask the knowledge base, nothing else. |
Outside its scope, a key gets 403:
{
"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.
- Main key: on the Integrations page, fill Allowed IPs and press Save allowed IPs. It is optional.
- API Messaging keys: the portal requires the list when it makes the key.
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:
{
"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: from that moment the old key gets 401. So rotate in this order:
- Make sure your system can take a new key quickly, from a secret store or an environment variable.
- Regenerate in the portal and copy the new key.
- Put it in place and restart whatever reads it.
Regenerating the main key does not touch your API Messaging keys, and each API Messaging key regenerates on its own. If a key leaks, regenerate it right away and tell us.