# API keys and the person a call is for

Each code of this family: what it means, its most frequent cause, what to do and who can do it.

[All error codes](https://www.azothos.ai/docs/errors)

### `api_key_invalid`

- **What it means**: The Azoth API key sent with the call matches no active key.
- **Most frequent cause**: A revoked or expired key, or a key copied with a character missing.
- **What to do**: This Azoth API key is not valid (revoked, expired or mistyped). Create a new one in Settings › Access.
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_missing`

- **What it means**: The call carries no Azoth API key.
- **Most frequent cause**: The `Authorization` or `X-Azoth-API-Key` header is missing, often because an environment variable is not set.
- **What to do**: No Azoth API key was sent. Paste a key from Settings › Access.
- **Who can do it**: The developer of the calling code

### `api_key_scope_denied`

- **What it means**: The key is valid, but it is limited — to scopes (the parts of the API it may call), to connectors or to environments — and this call falls outside those limits. At ingest, the answer’s `dimension` says which limit refused it: `connector` or `environment`.
- **Most frequent cause**: A key created for one use, such as ingest or reading, called another part of the API — or sent events for a connector or an environment the key was not created for.
- **What to do**: This API key is limited to some scopes, connectors or environments, and this call falls outside them. Create a key that covers it, or one with no such limits (unrestricted).
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_name_taken`

- **What it means**: A live key of the workspace already has the name asked for: two live keys of one workspace never share a name.
- **Most frequent cause**: A key created earlier with this name and never revoked — an expired key keeps its name until it is revoked.
- **What to do**: A live key of this workspace already has this name. Choose another name, or revoke that key in Settings › Access first.
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_role_denied`

- **What it means**: The key is valid, but its role — read, write or admin — is below what this route needs: a read key cannot call a route that writes, and an export of the workspace’s settings needs an admin key.
- **Most frequent cause**: A key created read-only, used by code that sends data or makes changes — or a key of another role than the one the integration was set up with.
- **What to do**: This API key’s role does not allow this call: a read key cannot write, and some exports need an admin key. Create a key with the needed role in Settings › Access.
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)

### `ip_not_allowed`

- **What it means**: The key is valid, but the call came from an address outside the workspace’s IP allowlist: the workspace accepts its API keys only from the addresses it lists.
- **Most frequent cause**: A new server, a cloud function or a network whose outbound address is not listed yet — or a proxy that changes the address the call comes from.
- **What to do**: This call came from an address outside the workspace’s IP allowlist. Call from a listed address, or ask an owner or admin to add this one.
- **Who can do it**: An owner or admin of the workspace

### `on_behalf_of_not_allowed`

- **What it means**: This call was blocked: its API key may not name the person it is for.
- **Most frequent cause**: Only a service key an owner or administrator allowed to may send X-Azoth-On-Behalf-Of. A personal key always speaks for its owner.
- **What to do**: Send the call without that header, or ask an owner or administrator for a service key allowed to name people (Settings › Access).
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)

### `human_identity_required`

- **What it means**: This call was blocked: it does not name the person it is for.
- **Most frequent cause**: This workspace requires every call to be attributed to a person, so that each decision can show who made it.
- **What to do**: Use your personal API key, or send X-Azoth-On-Behalf-Of (the person’s SCIM id or e-mail) with a service key allowed to name people.
- **Who can do it**: The developer of the calling code · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)

### `identity_unavailable`

- **What it means**: This call was blocked: the person it is for could not be checked.
- **Most frequent cause**: Azoth could not read the key or the workspace’s attribution rules, and does not serve a call it cannot attribute when attribution is required.
- **What to do**: Try again in a moment.
- **Who can do it**: Azoth, or the operator of this deployment

### `invalid_on_behalf_of`

- **What it means**: The `X-Azoth-On-Behalf-Of` header is not an identifier of a person Azoth can read.
- **Most frequent cause**: The header is empty, longer than 256 characters, or holds characters outside visible ASCII.
- **What to do**: X-Azoth-On-Behalf-Of must be 1 to 256 visible ASCII characters: send the person's SCIM id or e-mail.
- **Who can do it**: The developer of the calling code

### `key_not_bound_to_agent`

- **What it means**: The MCP gateway answers only an API key bound to one agent — the agent whose mandate decides what it may call — and this key is bound to none.
- **Most frequent cause**: A workspace key used instead of the key made for an agent in the MCP tools tab, or an agent key that was unbound since.
- **What to do**: This API key is bound to no agent. Create a key for the agent in the MCP tools tab of Mandates, and give that key to the MCP client.
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/mandats?tab=mcp)

### `invalid_key_identity`

- **What it means**: A personal key always speaks for its owner: it cannot also name other people.
- **Most frequent cause**: A personal key created with the option to name people turned on.
- **What to do**: To name people, create a service key with that option; a personal key is created without it.
- **Who can do it**: An owner or admin of the workspace · [Open the screen](https://www.azothos.ai/dashboard/settings?section=access)
