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

# Rotate keys

> Pre-claim agent key rotation (§8.1). Claimed or compromised? See Recover a compromised key.

Ed25519 auth keys don't need a rotation schedule — you rotate to migrate identifiers or to recover from compromise, not by the calendar. This guide covers **pre-claim** rotation, where the agent rotates its own key. For a **claimed** account, or any suspected compromise, the agent can't rotate itself — the owner recovers instead: see [Recover a compromised key](/guides/recover-a-compromised-key).

## Pre-claim rotation (§8.1)

While the account is `UNCLAIMED` or `INVITED`, the agent signs a rotation request with the **old** key:

```ts theme={null}
const newAgent = await Agent.generate();
const signed = await oldAgent.buildKeyRotation({ baseUrl, newDid: newAgent.did });
// POST signed → /afauth/v1/accounts/me/keys/rotate
```

`Server.handleKeyRotation` verifies the old key's signature, moves the account to the new DID, and adds the old DID to the revocation list (§8.3). A request signed by the old key afterwards fails with `401 revoked_key`.

<Note>
  **`did:key` changes the agent's DID on rotation** — the DID *is* the key, so external references to the old DID stop resolving; a caller holding the old DID updates its reference from the rotation response (`agent_did`). Agent credentials are `did:key` and AFAuth has no stable-identifier agent DID method, so recovery is owner-driven (revoke + re-key), not a persistent DID. (Post-claim, a service-side `account_id` is stable across re-key — §10.4.4 — so the account survives even as the DID rolls.) See [Identity and keys](/concepts/identity-and-keys).
</Note>

## Claimed accounts can't self-rotate

Post-claim, `handleKeyRotation` rejects an agent-signed rotation with `403` — changing a claimed account's key is an owner-binding operation, not something the agent's signature can authorize alone. The owner re-keys instead (§8.2). See [Recover a compromised key](/guides/recover-a-compromised-key).

Spec: [§8.1](https://github.com/AFAuthHQ/spec/blob/main/spec/core.md#81-pre-claim-key-rotation).