Getting started

Authentication

Every request to the Vollo API is authenticated with a workspace API key sent as a bearer token. Keys are scoped, revocable, and shown only once at creation.

API keys#

API keys belong to a workspace and start with the prefix pk_live_. Pass the key in the Authorization header of every request:

cURL / shellAuthenticated request

curl https://api.vollo.io/api/v1/projects \
  -H "Authorization: Bearer pk_live_8f3KJd92mA4qL7Zx1RttVWpc"

Requests without a valid key receive 401 Unauthorized with the standard error envelope:

JSON401 Unauthorized

{
  "message": "Unauthenticated."
}

Create keys in the dashboard under Settings → API Keys, or programmatically via POST /api-keys (requires a key that already holds the write scope). The full secret is returned exactly once, in the creation response — Vollo stores only a hash. Copy it into your secret manager immediately.

Scopes#

Each key carries a set of scopes. A request to an endpoint the key isn't scoped for returns 403 Forbidden. Grant the narrowest set that works:

Scope	Grants
`read`	Read access to all resources: list and retrieve projects, agents, workflows, sessions, calls, conversations, phone numbers, and SIP trunks.
`write`	Create, update, publish, and delete projects, agents, workflows, and API keys. Implies nothing about calls or telephony.
`calls:write`	Start outbound calls (`POST /calls`) and mint web sessions (`POST /sessions`).
`telephony`	Manage phone numbers, SIP trunks, and dispatch rules.
`usage:read`	Read usage and billing metrics (`GET /usage`).

A typical split: a backend service that only launches calls gets calls:write alone; a deployment pipeline that pushes workflow changes gets read + write; a metrics job gets usage:read.

JSON403 Forbidden — missing scope

{
  "message": "This API key does not have the required scope: calls:write."
}

Key rotation#

Rotate keys without downtime — multiple keys can be active at once:

Create a new key with the same scopes (POST /api-keys).
Deploy the new key to your services.
Watch the old key's last_used_at (visible in GET /api-keys and the dashboard) until it goes quiet.
Revoke the old key with DELETE /api-keys/{id}. Revocation is immediate and irreversible.

Rotate on a schedule that fits your compliance posture, and immediately if a key may have leaked — revoking takes effect on the next request.

Keep keys out of browsers#

Never expose API keys client-side

A pk_live_ key grants access to your whole workspace within its scopes. Never embed one in a browser bundle, a mobile app binary, or client-side source — anyone can extract it and place calls on your account.

For browser voice experiences, your server mints a short-lived session join token with its own key and hands only that token to the client. The join token is single-session, expires quickly, and grants nothing else.

Additional hygiene:

Load keys from environment variables or a secret manager — never commit them.
Use separate keys per service and per environment so a leak is contained and revocation is surgical.
Log the key's name, never its value; Vollo never logs full secrets either.

Rate limits#

The API allows 120 requests per minute per workspace, across all keys. Responses include the current window's state:

HTTPRate-limit headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87

Exceeding the limit returns 429 Too Many Requests with a Retry-After header (seconds). Back off and retry after that interval — see Errors → Rate limiting for the full shape and a retry recipe.