> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Claim Flow

> How an owner adopts a gateway-provisioned agent into their org. Claim is the second half of the gateway-first lifecycle — it gives an unclaimed agent an owner and a real org.

# 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
```

<Note>
  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.
</Note>

## 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`](/api-reference/endpoint/post-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](/concepts/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:

```bash theme={null}
# 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:

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

```bash theme={null}
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.

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

<CodeGroup>
  ```bash cURL theme={null}
  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\"
    }"
  ```

  ```typescript TypeScript theme={null}
  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: "…" }
  ```

  ```bash CLI theme={null}
  mnemom agents claim $AGENT_ID \
    --org acme \
    --key "$AGENT_PROVIDER_KEY" \
    --name my-agent
  # ✓ Claimed mnm-…. Landed in: Acme Corp (acme)
  ```
</CodeGroup>

### 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

```json theme={null}
{
  "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:

1. **Ownership is set.** `claimed_by` is your user/org; every subsequent policy and billing decision flows through your account.
2. **The agent is in your org.** It appears in `GET /v1/agents` results for that org.
3. **If `alignment_card.publish: true`**, the agent becomes discoverable in the Trust Directory at `/directory`.
4. **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](#between-steps-integrity-during-the-unclaimed-phase) for what was and was not recorded before claim.

Revoking ownership ([`DELETE /v1/agents/{id}`](/api-reference/endpoint/delete-agents-agent-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                                      |

***

## Related

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