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.

Between steps: integrity during the unclaimed phase

This is expected behavior, not a bug. Gateway-provisioned agents receive only a legacy alignment-card row at auto-provisioning time. No canonical alignment card is composed for them. Canonical cards are the prerequisite for the full integrity pipeline, so several downstream behaviors do not apply until after claim: No durable checkpoints. GET /v1/agents/{id}/checkpoints returns an empty list for unclaimed agents. This is expected and correct — checkpoints require a canonical alignment card. An empty checkpoint list is not a gap to investigate; it is the normal state for this provisioning tier. Verdict headers are fail-open, not analytical. The gateway still returns X-Mnemom-Verdict and X-AIP-Verdict headers on every request, but their values (clear / pass) come from the fail-open path — there is no canonical card to analyze against. These headers are not evidence that integrity analysis ran. Don’t confuse this with the unverified verdict value: unverified means a canonical card exists and analysis was attempted but failed (analyzer timeout/error); it never applies to unclaimed agents, since no analysis is attempted for them at all. AP-Traces are best-effort. The observer writes AP-Traces when Cloudflare metadata survives to the observer layer, but this is not guaranteed for unclaimed agents. Enforcement mode is observe. There is no owner to authorize a more active mode; nothing is blocked or nudged. How to get full integrity coverage. Claim the agent (Step 2 below). Once a canonical alignment card is composed — which happens as part of completing claim/onboarding — durable checkpoints begin, verdict headers reflect real analysis, and AP-Traces are guaranteed. The full integrity pipeline starts from 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\"
  }"

import { Mnemom } from "@mnemom/sdk";

const mnemom = new Mnemom({ apiKey: process.env.MNEMOM_API_KEY });

const result = await mnemom.agents.claim(agentId, {
  hashProof,          // SHA256(providerApiKey + '|' + agentName), 64-char hex
  orgId: "org-acme",  // optional — omit to land in your personal org
});
// result: { claimed: true, agentId: "mnm-…", orgId: "org-acme", claimedAt: "…" }

mnemom agents claim $AGENT_ID \
  --org acme \
  --key "$AGENT_PROVIDER_KEY" \
  --name my-agent
# ✓ Claimed mnm-…. Landed in: Acme Corp (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.

Logging in does not select an org. mnemom login authenticates you; the OAuth session carries no org context. Org placement is decided per command.

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.

Two ways to move an agent between orgs

	Re-claim (`POST /v1/agents/{id}/claim`)	Move (`POST /v1/agents/{id}/move`)
Authorization basis	Possession — you present the agent’s `hash_proof`	Role — you are an owner/admin of both the source and destination org
Needs the agent’s key	Yes	No
Org requirement	Member of the destination (role floor: member)	Owner/admin of source and destination
Typical use	The agent’s operator relocating their own agent	An org admin relocating agents they co-manage (e.g. personal → company org)

move takes { "dest_org_id": "org-…" } plus an Idempotency-Key header, and returns { moved, agent_id, from_org_id, to_org_id } (moving to the current org is an idempotent no-op, moved: false). Every move is recorded as an agent.org_moved governance audit row.

On either path, the destination org’s card template can floor/cap the agent’s composed alignment/protection values — the agent’s effective posture may change when it changes orgs. The canonical card is recomposed automatically as part of the move, and source-org team memberships are closed.

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.
The integrity pipeline starts from this point. A canonical alignment card is composed for the agent; durable checkpoints begin accumulating, verdict headers reflect real analysis, and AP-Traces are guaranteed. See Between steps: integrity during the unclaimed phase for what was and was not recorded before claim.

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).

Identity & Cards

Posture & Policy

Detection & Safe House

AEGIS

Reputation & Risk

Lifecycle

Self-register vs. claim — one question decides

How `hash_proof` proves key ownership

Step 1 — Agent routes its first gateway call

Between steps: integrity during the unclaimed phase

Step 2 — Owner claims the agent

Choosing the org

Response

Idempotency and re-homing

Two ways to move an agent between orgs

What changes after the claim

Common failure modes

​Self-register vs. claim — one question decides

​How hash_proof proves key ownership

​Step 1 — Agent routes its first gateway call

​Between steps: integrity during the unclaimed phase

​Step 2 — Owner claims the agent

​Choosing the org

​Response

​Idempotency and re-homing

​Two ways to move an agent between orgs

​What changes after the claim

​Common failure modes

​Related

Self-register vs. claim — one question decides

How `hash_proof` proves key ownership

Step 1 — Agent routes its first gateway call

Between steps: integrity during the unclaimed phase

Step 2 — Owner claims the agent

Choosing the org

Response

Idempotency and re-homing

Two ways to move an agent between orgs

What changes after the claim

Common failure modes

Related