Authentication
Create and use API keys, understand the organization and scopes a key covers, and handle authentication errors.
Last updated
Every request to the Victoria AI API is authenticated with an API key, sent as a Bearer token. A key belongs to one organization, and every request made with it reads and writes that organization's data.
Create a key
In the Victoria AI app, open Settings → API Keys and generate a key. Organization owners and admins can manage keys.
- Keys start with
vk_. - The full key is shown once, when you generate it. Victoria AI stores only a hash of the key, so it can't be shown again. Copy it into a secret manager or your deployment's environment variables straight away.
- Give each integration its own key, so you can revoke one without breaking the others.
Send the key
Put the key in the Authorization header of every request, after the word Bearer and a single space:
curl https://api.versionseven.ai/v1/auth/verify \
-H "Authorization: Bearer $VICTORIA_API_KEY"GET /v1/auth/verify needs no scope and returns the organization the key belongs to, which makes it a quick way to check a key.
Keep keys on your server. Don't put them in browser code or mobile apps, where anyone can read them.
Organizations
A key only ever sees its own organization's data. An ID that belongs to another organization is treated as if it doesn't exist:
- In the path, it answers a not-found error, such as
404 LEAD_NOT_FOUND. - In a request body, such as the
stage_idof a deal, it answers400, such as400 INVALID_STAGE.
Neither response confirms that the ID exists somewhere else.
Scopes
Each endpoint requires a scope, made of a resource family and an access level.
| Family | Covers |
|---|---|
leads | Leads and their campaign enrolments |
campaigns | Campaigns, sequences, analytics, queues, webhooks and reference data |
crm | Pipelines and deals |
accounts | Connected sender accounts |
The level is read or write, and write includes read: a key with leads:write can also call endpoints that need leads:read. A key without the scope an endpoint needs answers 403 INSUFFICIENT_SCOPE.
Keys generated in the Victoria AI app today have every scope, so they can call every endpoint.
Rotate a key
- Generate a new key in Settings → API Keys.
- Deploy your integration with the new key.
- Revoke the old key. Requests made with a revoked key answer
401 UNAUTHORIZED.
If a key is ever exposed, revoke it straight away.
Authentication errors
| Status | Code | Meaning |
|---|---|---|
401 | UNAUTHORIZED | The Authorization header is missing or malformed, or the key is unknown or revoked. |
401 | API_KEY_EXPIRED | The key is past its expiry date. |
403 | INSUFFICIENT_SCOPE | The key doesn't have the scope the endpoint requires. |
403 | ORGANIZATION_DEACTIVATED | The organization that owns the key has been deactivated. |
503 | AUTH_UNAVAILABLE | The key couldn't be checked. Retry after a short wait. |
A header counts as malformed unless it's exactly Bearer, one space, and the key.