Authentication & API keys
Create API keys, send them on every request, and limit what each key can do.
Every request to the CallMitra API is authenticated with an API key sent in the X-API-Key header.
curl https://api.callmitra.ai/api/v1/leads/?limit=5 \
-H "X-API-Key: vk_live_..."If your HTTP client prefers the standard Authorization header, send the same key as a bearer token instead. When both headers are present, X-API-Key wins.
curl https://api.callmitra.ai/api/v1/leads/?limit=5 \
-H "Authorization: Bearer vk_live_..."All requests must use HTTPS. Keys work only under /api/v1.
| Problem | Status | Code |
|---|---|---|
| No key sent | 401 | unauthenticated |
| Unknown or revoked key | 401 | invalid_api_key |
| Key past its expiry date | 401 | api_key_expired |
| Endpoint that no key may call | 403 | api_key_route_forbidden |
| Outside the key's access or resources | 403 | api_key_scope_denied |
| Too many requests for this key | 429 | rate_limit_exceeded |
Create a key
- In the console, open Settings → Developers.
- Choose Create key, name it after the integration that will use it, and choose its access and expiry.
- Copy the secret. It starts with
vk_live_and is shown once; CallMitra stores only a hash. The console keeps the first characters (the key prefix) so you can recognise the key later.
Only workspace managers can create and revoke keys. Other team members see only the keys they created. Keys cannot be created, listed or revoked through the API, and a key cannot be created while you are working inside an agency client workspace: create it in your own workspace instead (Agencies).
Revoking a key in the console stops it on the very next request.
A workspace can hold a limited number of unexpired keys (20 by default). Creating another fails with api_key_limit_reached; revoke a key you no longer use first.
Keys belong to the workspace
A key belongs to your workspace, not to the person who created it. It sees that workspace's data, and the console shows who created it.
- While its creator is still an active member of the workspace, the key acts as that person with their current role. It gets the same data access and shows the same name in the audit log. If a manager is later made a lead, their keys act as a lead from the next request. A key never has more access than its creator.
- If the creator is deleted, suspended or blocked, or moves to another workspace, the key keeps working. It then acts as the workspace's primary manager, the earliest-created active manager. Each switch like this is written to the audit log as
api_key.actor_fallback, at most once per key per UTC day. Revoke the key in Settings → Developers when an integration should stop. - If the workspace has no active manager left, the key answers
401invalid_api_key. - If the workspace itself is suspended, keys stop working until it is active again.
- Keys created by CallMitra platform staff accounts are refused with
403; staff work in the admin console with multi-factor authentication.
Limit what a key can do
When you create a key you choose:
| Option | Values | Effect |
|---|---|---|
| Access | Full or Read only | A read-only key can only send GET (and HEAD/OPTIONS) requests. Anything that changes data answers 403 api_key_scope_denied with the message This API key is read-only. |
| Can access | All resources, or a list | A key limited to resources answers 403 api_key_scope_denied on every endpoint outside them. |
| Expiry | 30 days, 90 days (the default), 1 year, or does not expire | After expiry the key answers 401 api_key_expired. Create a new key and revoke the old one. |
Resources and the endpoints they cover:
| Resource | Covers |
|---|---|
| Leads | Leads, lead notes, do-not-call, lead sources, fields, segments, lead integrations, search |
| Campaigns | Campaigns, dialing controls, instant calls, callbacks and reminder rules, inbound routing, handoff |
| Calls | Call history, results and recordings |
| Agents | Agents, voices, tools, templates, background sounds, MCP servers |
| Numbers | Phone numbers and SIP trunks |
| WhatsApp messaging and engagement | |
| Tickets | Tickets |
| Webhooks | Webhook endpoints, deliveries and event types, an agent's post-call webhook, CRM webhooks and integrations |
A limited key fails closed: if an endpoint does not belong to one of its resources, the request is refused. An agent's post-call webhook can be managed by a key with either Agents or Webhooks. GET /workspace and GET /usage are readable by every key, whatever its resources.
Give each integration its own key
Use a separate key per system, with the smallest access it needs and an expiry. If one leaks, revoke just that key.
Which endpoints a key can call
A key can call only the endpoints listed in the API reference, under /api/v1. Every other route answers 403 api_key_route_forbidden, whatever the key's access. That includes /platform/v1 paths and console-only routes such as:
- everything under
/auth: sign-in, sessions, passwords, multi-factor authentication, and the signed-in user's profile (GET /auth/me); - creating, listing or revoking API keys (
/api-keys); - team members, roles and suspensions;
- deleting or exporting the whole workspace;
- platform administration and platform runtime settings;
- billing changes and agency client-workspace changes.
A key's access settings narrow this list further; they can never open a route that is not in the reference. When an endpoint is added to the reference, keys can call it from then on.
Checking which workspace a key belongs to
GET /auth/me is a console endpoint, so keys get 403 there. Call GET /api/v1/workspace instead: it returns the workspace the key works in and details of the key itself. See Workspace and usage.
Rate limits
Each key has its own budget of 300 requests per minute, separate from other keys and from your team's console sessions. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. See Rate limits.
Keep keys safe
- Keep keys on your server. Never ship them in a web page, mobile app or public repository.
- Store them in a secret manager or environment variable, not in source code.
- Rotate: create the new key, deploy it, then revoke the old one.
- If a key may have leaked, revoke it immediately in Settings → Developers.
Related
- Agencies: one key for every client workspace with
X-Workspace-Id. - Rate limits: each key has its own per-minute budget.
- Errors: every
401and403code with how to fix it.