Skip to content
VoDialerDocs

API keys and scopes

An API key lets your software talk to VoDialer without a person signing in. Each key can only do what you tick when you make it.

Do this

Section titled “Do this”
  1. Open Setup, then Integrations, then the API keys tab. You need to be an owner or an admin.
  2. Press New key. A box titled “New API key” opens.
  3. Under “What is it for”, type a name you will recognise, such as “Our CRM”.
  4. Under “What it may do”, tick only the scopes you need. See below.
  5. Press Make the key. A box shows the key once. Copy it into your secret store now.
  6. Send it with every request as an Authorization header: Bearer followed by the key.
Terminal window
curl https://YOUR-HOST/api/core/v1/campaigns \
  -H "Authorization: Bearer vd_live_xxxxxxxxxxxxxxxx"

A key starts with vd_live_. The list afterwards shows only its first 12 characters, a name, the scopes and when it was made.

Scopes

Section titled “Scopes”
Scope Screen label What the key may do
read Read GET requests to core (campaigns, lists, people, results), compliance, dialer and insights.
leads:write Add people POST /api/integrations/v1/inbound/leads.
dnc:write Add to do-not-call POST /api/integrations/v1/inbound/dnc.
outcomes:write Report outcomes POST /api/integrations/v1/inbound/outcomes.

A key can do nothing else. It cannot change connections, campaigns or people, and it cannot reach the web app’s own endpoints. The three write scopes are checked one by one: a key with leads:write cannot post do-not-call numbers.

The inbound endpoints are in the inbound API.

Revoking a key

Section titled “Revoking a key”

Open the key’s row menu, choose Revoke and confirm. “Anything using this key stops working at once. This cannot be undone.” If your company is suspended, all its keys stop at once too.

Limits

Section titled “Limits”
  • Rate. The default is 200 requests per second for the whole company, with bursts up to 1,000. The people using the web app and every key share it. Past it you get 429. Wait the number of seconds in the Retry-After header.
  • Body size. Most requests may be up to 10 MB. Over the limit you get 413.
  • No cookies, no CSRF. A key does not use the sign-in cookie, so the CSRF header does not apply.

Errors

Section titled “Errors”

Every error has the same shape:

{ "error": { "code": "forbidden", "message": "api key lacks the required scope" } }
Status code Meaning
400 bad_request The request could not be read.
401 unauthorized The key is missing, wrong or revoked.
403 forbidden The key lacks the scope, or this endpoint is not open to keys.
404 not_found There is nothing at that address.
409 conflict A request with that Idempotency-Key is still running.
413 payload_too_large The body is over the limit.
422 unprocessable The body is readable but not valid. The message says why.
429 too_many_requests Slow down. Read Retry-After.
503 unavailable A part of VoDialer is not running. Try again.