Skip to main content
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.

​
Pre-claim rotation (§8.1)

While the account is UNCLAIMED or INVITED, the agent signs a rotation request with the old key: 
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.
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.

​
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. Spec: §8.1.