Authentication

API Keys

API keys are used to authenticate your requests. You can create and manage your API keys in your account settings under Settings → API Keys.

Using your API key

Include your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

Here's an example using cURL:

curl -X GET "https://vocalis.io/api/v1/contact-lists" \
  -H "x-api-key: YOUR_API_KEY"

Key Format

API keys use the following format:

Organizations and Scopes

A key belongs to one organization — the one you were working in when you created it. It reads and writes only that organization's data, even if your own account belongs to several. A request for a resource in another organization returns 404, the same answer as a resource that does not exist.

By default a key can do everything you can do in that organization. Narrow it by listing capabilities when you create it, and it can do only those — useful for a key that lives in a script, a partner integration, or anywhere the blast radius matters more than convenience.

{
  "name": "Reporting export",
  "scopes": ["call:read", "campaign:read"]
}

Scopes are capability names in resource:action form. Each endpoint's reference page names the capability it requires. A request outside a key's scopes is refused with 403 INSUFFICIENT_SCOPE, and the refusal names the capability that was missing.

Rate Limits

Each API key has rate limits to ensure fair usage:

• 60 requests per minute (RPM)
• 10,000 requests per day (RPD)

Authentication Errors

If authentication fails, you'll receive one of these error responses: