Error codes
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.
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
api_key_missing
- What it means
- The call carries no Azoth API key.
- Most frequent cause
- The
AuthorizationorX-Azoth-API-Keyheader 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
dimensionsays which limit refused it:connectororenvironment. - 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
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
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
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
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
invalid_on_behalf_of
- What it means
- The
X-Azoth-On-Behalf-Ofheader 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
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