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

# Rotating Your Agent's API Key

> How to update an agent's provider key binding without losing history

# Rotating your agent's API key

When you rotate a provider API key (Anthropic, OpenAI, or Gemini), Mnemom would normally treat the new key as a brand-new, unregistered agent — losing your traces, alignment card, integrity score, and trust edges. **Rekeying** re-binds your existing agent to the new key in seconds, with no history lost.

## How it works

Your agent is identified by the first 16 characters of the SHA-256 hash of your provider API key. Mnemom never stores or transmits your raw key — only this short hash. Rekeying atomically swaps the stored hash to match your new key, keeping the agent ID and all associated data intact.

The operation is:

* **Atomic** — conflict detection and hash swap happen in a single database transaction
* **Privacy-preserving** — your raw API key is hashed client-side before any network call
* **Non-destructive** — agent ID, traces, alignment card, integrity score, and trust edges are unchanged

## Prerequisites

* Your agent must be [claimed](/gateway/overview) and linked to your Mnemom account
* You must have your new provider API key ready before starting

## Option 1: Dashboard

<Steps>
  ### Navigate to your agent

  Open your agent dashboard and select the **Security** tab.

  ### Open the API key section

  Scroll to **API Key** at the bottom of the Security tab and click **Rotate Key**.

  ### Confirm the operation

  Read the confirmation dialog, then click **Continue**.

  ### Enter your new key

  Enter your new provider API key in the input and confirm it. The key is hashed in your browser before being sent — it is never transmitted in raw form.

  ### Done

  A success notification confirms the re-binding. Update your `ANTHROPIC_API_KEY` (or equivalent) environment variable.
</Steps>

## Option 2: API

Compute the SHA-256 hash of your new key **client-side**, then POST it:

```bash theme={null}
# Unnamed agent: hash the key directly
NEW_HASH=$(printf '%s' 'your-new-api-key' | sha256sum | cut -c1-16)

curl -X POST https://api.mnemom.ai/v1/agents/mnm-550e8400-e29b-41d4-a716-446655440000/rekey \
  -H "Authorization: Bearer <your-mnemom-token>" \
  -H "Content-Type: application/json" \
  -d "{\"new_key_hash\": \"$NEW_HASH\"}"
```

**Named agents** (registered with `x-mnemom-agent` header — the name is included in the hash):

```bash theme={null}
NEW_HASH=$(printf '%s' 'your-new-api-key|my-coder' | sha256sum | cut -c1-16)
```

Replace `my-coder` with the exact name used when the agent was registered. Check your agent details in the dashboard or via `GET /v1/agents/{agent_id}` to confirm the name.

**Success response:**

```json theme={null}
{
  "success": true,
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "rekeyed_at": "2026-03-31T12:00:00.000Z"
}
```

## Reading your key prefix

After your first gateway request following this update, your agent displays the first 16 characters of its bound provider key — enough to identify the provider and key type without exposing sensitive material.

| Provider  | Example prefix     |
| --------- | ------------------ |
| Anthropic | `sk-ant-api03-xx…` |
| OpenAI    | `sk-proj-xxxxxxx…` |
| Gemini    | `AIzaSyBxxxxxxxx…` |

Agents registered before this feature was shipped will show "Prefix not available" until they make their next gateway request, at which point the prefix is captured automatically.

## Verifying your key binding

Not sure which key is bound to your agent? Use verify binding to confirm without rekeying.

### Dashboard

In the agent Security tab, click **Verify my key** below the current key prefix display. Enter your key — the result appears inline.

### API

```bash theme={null}
KEY_HASH=$(printf '%s' 'your-api-key' | sha256sum | cut -c1-16)

curl -X POST https://api.mnemom.ai/v1/agents/mnm-550e8400-e29b-41d4-a716-446655440000/verify-binding \
  -H "Authorization: Bearer <your-mnemom-token>" \
  -H "Content-Type: application/json" \
  -d "{\"key_hash\": \"$KEY_HASH\"}"
```

Response:

```json theme={null}
{ "bound": true, "caller": "org_member", "key_prefix": "sk-ant-api03-xx" }
```

## Multiple named agents from the same key

If you registered multiple named agents from the same provider key, each holds a distinct hash:

* Agent A: `SHA256(key|nameA).slice(0, 16)`
* Agent B: `SHA256(key|nameB).slice(0, 16)`

You must **rekey each agent independently**, using the correct hash for each name. Use the dashboard or API to rekey each one:

```bash theme={null}
# Via API — rekey agent-a
NEW_HASH_A=$(printf '%s' 'your-new-api-key|agent-a' | sha256sum | cut -c1-16)
curl -X POST https://api.mnemom.ai/v1/agents/AGENT_A_ID/rekey \
  -H "Authorization: Bearer <your-mnemom-token>" \
  -H "Content-Type: application/json" \
  -d "{\"new_key_hash\": \"$NEW_HASH_A\"}"

# Via API — rekey agent-b
NEW_HASH_B=$(printf '%s' 'your-new-api-key|agent-b' | sha256sum | cut -c1-16)
curl -X POST https://api.mnemom.ai/v1/agents/AGENT_B_ID/rekey \
  -H "Authorization: Bearer <your-mnemom-token>" \
  -H "Content-Type: application/json" \
  -d "{\"new_key_hash\": \"$NEW_HASH_B\"}"
```

## Resolving key conflicts

If you used your new key to make a request **before rekeying**, the gateway auto-created a shadow agent for it. The rekey endpoint returns `409 Conflict` with the shadow agent's ID.

**To resolve:**

1. Note the `conflict_agent_id` from the error (`409` response body or CLI output)
2. In your dashboard, navigate to the shadow agent and **Deactivate** it (Settings tab → Deactivate)
   * Only do this if the shadow agent is unclaimed and has no meaningful history
3. Retry the rekey

<Note>
  If the shadow agent has traces you want to keep, contact [support@mnemom.ai](mailto:support@mnemom.ai) before deactivating it.
</Note>

## Security notes

* **The raw API key is never transmitted to Mnemom.** Only the 16-character SHA-256 prefix is sent.
* The rekey operation is **rate-limited** per account to prevent abuse.
* After rekeying, the old key no longer identifies this agent. Any infrastructure still using the old key will auto-create a new, unclaimed agent — rotate your environment variable promptly.
* The `rekeyed_at` timestamp and a `rekey_count` are stored on the agent for audit purposes.