---
title: "Re-bind agent to a new API key"
method: POST
path: "/agents/{agent_id}/rekey"
tags: ["Agents"]
---

# Re-bind agent to a new API key

`POST /agents/{agent_id}/rekey`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/agents/{agent_id}/rekey`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`

Updates the agent's key binding to a new provider API key hash. The agent ID, traces, alignment card, integrity score, and trust edges are fully preserved.

**Security model**: Your API key is hashed on your device (SHA-256) before transmission — the raw key is never sent to Mnemom servers.

**Named agents**: If this agent was registered with a name (via `x-mnemom-agent`), hash the new key as `SHA256(newKey + '|' + agentName)` before submitting.

**Conflict**: If the new key was already used and auto-created a new agent, the endpoint returns `409` with the conflicting agent ID.

**Authorization**: `agent_id` is resolved to its governing organization from the DB and the caller must be an owner, admin or member of that org. An agent in another org, or an unknown agent, returns `403` before the body is read, so no one can rebind another tenant's agent to a key they control. Possession of the old key is deliberately not required: rekey is the recovery path for a lost or compromised key, and the org-membership check is what gates it.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `new_key_hash` string, required: First 16 hex characters of SHA256(newApiKey) for unnamed agents, or SHA256(newApiKey + '|' + agentName) for named agents. Compute client-side — do not transmit the raw key.
  - `key_prefix` string: First 16 characters of the new provider API key. Stored for display — not sensitive. If provided, returned in the response.

## Response `200`

Agent successfully re-bound to the new key.

- object
  - `success` boolean
  - `agent_id` string
  - `rekeyed_at` string, date-time

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `409`: Resource conflict — the request cannot proceed because of a current state conflict (e.g., resource already exists, version mismatch, in-flight idempotency key with a different body).
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/e13923bd55ef?raw)