Getting started
Authentication
Every request carries an API key as a bearer token. Keys are region bound and cannot be moved between deployments.
Bearer token
Send the key in the Authorization header on every call:
Authorization: Bearer rcd_eu_a1b2c3d4_...Keys are shown once, at creation. Recalld stores only a hash, so a lost key cannot be recovered: revoke it and mint a new one.
Key format
Keys are structured as rcd_<region>_<prefix>_<secret>:
| Segment | Meaning |
|---|---|
| rcd | Format tag. Keys issued before the rename carry amk and still work. |
| region | Two-letter region code, for example eu or us. |
| prefix | Public lookup handle. Safe to log, shown in the dashboard. |
| secret | The part that authenticates. Never logged, never recoverable. |
Restricting a key to agents
By default a key can act as any agent in the account: the agent is chosen by
the agent_id in the URL, and agent ids are not secret. When you
create a key you can tick the agents it may use. A restricted key gets
403 on every other agent, so an agent that holds it cannot read
or write another agent's memory, even if it learns the id. A restricted key
cannot create agents either. Leave the list empty for a key that may use
every agent.
Task memory is not restricted by keys. Any allowed agent that knows a
task_id can read the shared pool.
Sending a key to the wrong region
Regions are separate deployments with separate databases. A European key presented to the US host is rejected: the host that would have to validate it has no record of it. The error names both regions so you can see the mismatch:
api key belongs to region "eu", this is region "us"Read Regions for the full model.
Common responses
| Status | Meaning |
|---|---|
| 401 | Missing, malformed, or revoked key. |
| 403 | Valid key shape, but wrong region, the agent does not belong to this key's account, or the key is restricted to other agents. |
| 429 | Plan rate limit exceeded. Limits are per plan, see Plans. |
MCP clients authenticate differently
The MCP endpoint does not accept API keys. It runs its own OAuth flow, and the agent is bound when the connection is authorized. See MCP integration.