# Authentication & API keys (/authentication)

Every request to the CallMitra API is authenticated with an API key sent in the `X-API-Key` header.

```bash
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.

```bash
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`](/errors/unauthenticated) |
| Unknown or revoked key | `401` | [`invalid_api_key`](/errors/invalid_api_key) |
| Key past its expiry date | `401` | [`api_key_expired`](/errors/api_key_expired) |
| Endpoint that no key may call | `403` | [`api_key_route_forbidden`](/errors/api_key_route_forbidden) |
| Outside the key's access or resources | `403` | [`api_key_scope_denied`](/errors/api_key_scope_denied) |
| Too many requests for this key | `429` | [`rate_limit_exceeded`](/errors/rate_limit_exceeded) |

## Create a key [#create-a-key]

1. In the console, open **Settings → Developers**.
2. Choose **Create key**, name it after the integration that will use it, and choose its access and expiry.
3. 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](/guides/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`](/errors/api_key_limit_reached); revoke a key you no longer use first.

## Keys belong to the workspace [#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 `401` `invalid_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 [#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`](/errors/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`](/errors/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`](/errors/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 | 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`](/api-reference/workspace/getWorkspace) and [`GET /usage`](/api-reference/workspace/getUsage) are readable by every key, whatever its resources.

<Callout title="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.
</Callout>

## Which endpoints a key can call [#which-endpoints-a-key-can-call]

A key can call only the endpoints listed in the [API reference](/api-reference), under `/api/v1`. Every other route answers `403` [`api_key_route_forbidden`](/errors/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.

<Callout title="Checking which workspace a key belongs to">
`GET /auth/me` is a console endpoint, so keys get `403` there. Call [`GET /api/v1/workspace`](/api-reference/workspace/getWorkspace) instead: it returns the workspace the key works in and details of the key itself. See [Workspace and usage](/guides/workspace-usage).
</Callout>

## Rate limits [#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](/rate-limits).

## Keep keys safe [#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 [#related]

- [Agencies](/guides/agencies): one key for every client workspace with `X-Workspace-Id`.
- [Rate limits](/rate-limits): each key has its own per-minute budget.
- [Errors](/errors): every `401` and `403` code with how to fix it.