> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# DID Key Rotation Sequence

**Used in:** §3.1.5 Key Rotation, §9.3
**Audience:** Holder, Backend Developer
**IA ID:** D2 detail

```mermaid
sequenceDiagram
  autonumber
  participant Holder
  participant Portal
  participant API
  participant DB
  participant DIDRegistry

  Holder->>Portal: Initiate "Rotate key"
  Portal->>API: POST /api/v1/dids/{did}/rotate-key
  API->>API: Verify caller owns DID (RBAC + DID owner check)
  API->>API: Generate new Ed25519 keypair
  API->>API: Build updated DID Document (new verificationMethod)
  API->>DIDRegistry: updateDID(did, newDocument) signed by current owner
  DIDRegistry-->>API: emit DIDUpdated
  API->>DB: UPDATE did SET pubkey=..., updated=now()
  API->>DB: INSERT did_key_history (old pubkey, rotated_at)
  API-->>Portal: 200 OK { did, newPubKey, txHash }
  Portal-->>Holder: Show new key + audit log entry
```

**Reading guide:** The old key remains in `did_key_history` for replay-attack diagnostics; only the latest verificationMethod is authoritative.

***