Agent claim flow

When an agent routes its first request through the Mnemom gateway, the gateway automatically registers it and parks it in the Mnemom Sandbox — a system holding org with no owner. Claiming is how that agent gets an authenticated owner and moves into a real org. It is the canonical second half of the gateway-first lifecycle:

gateway first-traffic  →  Mnemom Sandbox (unclaimed)  →  claim  →  your org

This is the EN-only doc by design — every page under docs/api-reference/* and this claim guide stay English to match the convention every major API platform (Stripe, GitHub, AWS, GCP) ships. Localized translations of the conceptual + tutorial docs are in flight as part of T7; the API-shaped surfaces are not in scope.

Self-register vs. claim — one question decides

Are you the agent, or are you adopting a pre-existing one?

You are the agent → use POST /v1/agents. This creates a new agent owned by you in one authenticated call — no separate claim step.
You are adopting a gateway-provisioned agent → use POST /v1/agents/{id}/claim (this guide). The agent already exists; you prove you hold its key and assign it to your org.

These answer different questions; neither is legacy. See Agent identity § Registration for the full comparison.

How `hash_proof` proves key ownership

hash_proof is the full 64-character lowercase hex output of:

hash_proof = SHA256(providerApiKey + '|' + agentName)  # named agent (has x-mnemom-agent header)
hash_proof = SHA256(providerApiKey)                    # unnamed singleton (no x-mnemom-agent)

where providerApiKey is the agent’s Anthropic / OpenAI / Gemini key — the key the agent uses in the x-api-key / Authorization: Bearer / x-goog-api-key header on gateway calls. The API compares this against the stored proof and never sees the raw key. Compute it locally before calling claim:

# Named agent
HASH_PROOF=$(printf '%s|%s' "$AGENT_PROVIDER_KEY" "my-agent" | shasum -a 256 | awk '{print $1}')

# Unnamed singleton
HASH_PROOF=$(printf '%s' "$AGENT_PROVIDER_KEY" | shasum -a 256 | awk '{print $1}')

Note that two different keys are involved in a claim call:

Key	Variable	Purpose
Agent’s provider key (Anthropic / OpenAI / Gemini)	`$AGENT_PROVIDER_KEY`	Derives `hash_proof` — proves you hold the agent’s identity key
Your Mnemom key / JWT	`$MNEMOM_API_KEY`	Authenticates you as the owner — you become `claimed_by`

Step 1 — Agent routes its first gateway call

No extra setup required. When the agent makes a normal request through the gateway with its provider key (and optionally x-mnemom-agent: <name>), the gateway:

Hashes the provider key (+ name) to compute agent_hash.
Finds no existing agent with that hash, so creates one.
Parks it in the Mnemom Sandbox holding org with claim_state: unclaimed.
Returns the assigned mnm-* agent ID in the x-mnemom-agent response header.

curl https://gateway.mnemom.ai/anthropic/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "x-mnemom-agent: my-agent" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 256, "messages": [{"role": "user", "content": "Hello"}]}'
# Response header → x-mnemom-agent: mnm-550e8400-e29b-41d4-a716-446655440000

Record the mnm-* ID — you’ll need it to claim.

Step 2 — Owner claims the agent

Authenticated as the owner — a Bearer JWT (from mnemom login), an mnm_* API key (X-Mnemom-Api-Key), or a session cookie — call the claim endpoint. Standard auth is all it takes; there is no special claim-only scheme. You prove you hold the agent’s provider key by sending hash_proof; the principal you authenticate as becomes the agent’s owner.

HASH_PROOF=$(printf '%s|%s' "$AGENT_PROVIDER_KEY" "my-agent" | shasum -a 256 | awk '{print $1}')

curl -X POST "https://api.mnemom.ai/v1/agents/$AGENT_ID/claim" \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "content-type: application/json" \
  -d "{
    \"hash_proof\": \"$HASH_PROOF\",
    \"org_id\": \"org-acme\"
  }"

Choosing the org

Pass org_id to place the agent in a specific org. You must be a member (owner, admin, or member). An org you don’t belong to → 403 agent_org_not_member; the error details carry requested_org_id and claimable_orgs.
Omit org_id and the agent lands in your personal org — the smallest-blast-radius default. To place the agent in a shared or company org, name it explicitly.

List your orgs with GET /v1/orgs (or mnemom org list) to find the right org_id.

Response

{
  "claimed": true,
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "org_id": "org-acme",
  "claimed_at": "2026-05-18T22:15:00Z"
}

The response always reports the resolved org_id, so you know exactly where the agent landed.

Idempotency and re-homing

Think of claim as a declarative assertion: “this agent is mine, and it lives in the org I name.” Repeating that assertion as the rightful owner is always safe:

Re-claim with the same (or no) org_id → no-op success; claimed_at is preserved.
Re-claim with a new org_id → the agent is moved to that org. Claim is also how you move an agent between your orgs.

There is no 409 on claim. An agent already owned by a different principal returns 403 agent_cross_tenant — hash_proof lets you claim an unowned agent; it never lets you take over one that already has an owner.

What changes after the claim

Once the agent is claimed:

Ownership is set. claimed_by is your user/org; every subsequent policy and billing decision flows through your account.
The agent is in your org. It appears in GET /v1/agents results for that org.
If alignment_card.publish: true, the agent becomes discoverable in the Trust Directory at /directory.

Revoking ownership (DELETE /v1/agents/{id}) is an owner-side operation.

Common failure modes

Symptom	Likely cause	Fix
`401`	No credentials presented, or JWT expired	Add `Authorization: Bearer <jwt>`, `X-Mnemom-Api-Key: <mnm_key>`, or a valid session cookie
`400 hash_proof_required`	Body missing `hash_proof`	Compute and include `hash_proof`
`400 invalid_key_hash_format`	`hash_proof` is not 64 lowercase hex characters	Recompute using SHA256 and verify output length
`403 agent_org_not_member`	`org_id` is one you don’t belong to	Use an org from `details.claimable_orgs`, or omit `org_id` to land in personal org
`403 agent_cross_tenant`	Agent already owned by a different principal	Cannot adopt another owner’s agent
`404`	`agent_id` doesn’t exist, or doesn’t exist yet	Verify the `mnm-*` ID from the `x-mnemom-agent` response header
Network 5xx during claim	Transient gateway issue	Safe to retry — claim is idempotent for the same owner

Agent Identity — the full registration model, agent_hash formula, and self-register vs. claim comparison.
Authentication — the owner-side auth methods (passkey, AAL2, SSO, API keys) that gate the claim endpoint.
POST /v1/agents/{id}/claim — endpoint reference with full request/response schema.
POST /v1/agents — self-register path (creates and owns in one authenticated call).

​Agent claim flow

​Self-register vs. claim — one question decides

​How hash_proof proves key ownership

​Step 1 — Agent routes its first gateway call

​Step 2 — Owner claims the agent

​Choosing the org

​Response

​Idempotency and re-homing

​What changes after the claim

​Common failure modes

​Related

Agent claim flow

Self-register vs. claim — one question decides

How `hash_proof` proves key ownership

Step 1 — Agent routes its first gateway call

Step 2 — Owner claims the agent

Choosing the org

Response

Idempotency and re-homing

What changes after the claim

Common failure modes

Related