Key Rotation¶

Key rotation replaces your active signing key while preserving your did:keri identity. Auths uses KERI pre-rotation, which means the next rotation key is cryptographically committed to before it is ever needed.

When to rotate keys¶

Scheduled key hygiene -- periodic replacement to limit the window of any potential compromise
Suspected compromise -- the current key may have been exposed
Personnel change -- a team member with access to the key is leaving
Emergency response -- use auths emergency rotate-now for immediate rotation with an interactive safety flow

How rotation works¶

When your identity is created (auths init), two keypairs are generated (P-256 by default):

Current key -- used for signing now
Next key -- a pre-committed rotation key, stored encrypted in the keychain under a derived alias (<alias>--next-<sequence>)

A hash of the next key's public key is included in the inception event. This creates a binding: only the holder of the pre-committed next key can perform a valid rotation.

flowchart LR
    subgraph ICP["Inception Event (s=0)"]
        A_cur["current_key: pk_A"]
        A_next["next_commitment: hash(pk_B)"]
    end
    subgraph ROT["Rotation Event (s=1)"]
        B_prev["previous_key: pk_A"]
        B_cur["current_key: pk_B"]
        B_next["next_commitment: hash(pk_C)"]
    end
    A_next -- "pk_B matches commitment" --> B_cur

After rotation:

pk_B becomes the active signing key
pk_C is pre-committed for the next rotation
A new rotation event is appended to the Key Event Log (KEL)
The old pre-committed key alias is cleaned up from the keychain

Performing a rotation¶

Standard rotation¶

auths id rotate --alias my-key

This uses the current key alias to find the pre-committed next key, generates a fresh future rotation key, and appends a rotation event to the KEL.

You will be prompted for:

The passphrase for the pre-committed next key
A new passphrase for the rotated key alias (entered twice for confirmation)

Specifying a new alias¶

auths id rotate --alias my-key --next-key-alias my-key-v2

After this command, my-key-v2 is the active signing key alias. The CLI updates git's user.signingKey for you; update any CI secrets that reference the old alias. (Without --next-key-alias, the alias stays the same and nothing needs updating.)

Using `--current-key-alias` (alternative flag)¶

auths id rotate --current-key-alias my-key --next-key-alias my-key-v2

The --current-key-alias flag is equivalent to --alias and cannot be combined with it.

Modifying witness configuration during rotation¶

auths id rotate --alias my-key \
  --add-witness "B<prefix>" \
  --witnesses-required 1

Flag	Description
`--add-witness <PREFIX>`	Add a witness prefix (repeatable)
`--remove-witness <PREFIX>`	Remove a witness prefix (repeatable)
`--witnesses-required <N>`	Number of witnesses required to accept this rotation

Emergency rotation¶

For suspected key compromise, use the emergency rotation flow:

auths emergency rotate-now

This launches an interactive flow that:

Prompts for the current signing key alias
Prompts for a new key alias
Requires typing ROTATE to confirm
Performs the rotation
Refreshes the commit-trailer file and prints a post-rotation checklist

Delegated devices survive rotation

Rotation changes the root's active key, not your devices' delegations — those are anchored in the key event log, and verifiers replay the log to resolve authority at any point in time. Signing and verification work immediately after rotation with no extra steps. (Only the legacy attestation-linked flow — auths device link — produced attestations that may need re-issuing.)

For non-interactive use (CI, scripts):

auths emergency rotate-now \
  --current-alias my-key \
  --next-alias my-key-v2 \
  --reason "Suspected key exposure" \
  --yes

Use --dry-run to preview actions without making changes:

auths emergency rotate-now --dry-run

What happens to old signatures after rotation¶

The honest answer has two halves:

Attestations and signed artifacts remain valid. They are verified against the key that was active at their recorded signing time — the Key Event Log proves which key that was, so rotation never invalidates artifact or attestation history.

Old commits get a precise classification, not a pass. Commit verification checks the signer's current key. A commit signed before a rotation returns the explicit verdict SignedBySupersededKey — the verifier recognizes the signature as a legitimate former key that has since rotated away, clearly distinguished from an unknown or forged signer. This is deliberate: silently accepting any historical key would let a stolen old key forge "old" commits (a backdating attack). If your policy requires old commits to verify green under the current key, re-sign them with auths sign <ref> — note this amends the commits, so SHAs change; never rewrite pushed history without coordinating.

What stays the same¶

Your did:keri:E... identifier
Your key alias (main stays main — git signing config, the commit hook, and CI env blocks keep working untouched)
Your attestation history and artifact signature validity
Your device and agent delegations

What changes¶

The active signing key (the keypair used for new signatures; stored under the same alias)
The KEL gains a rotation event entry
Pre-rotation commits verify as SignedBySupersededKey (recognized legacy) rather than valid
The rotated-away private key is deleted from the keychain — it must never sign again, and verification only ever needs the public keys recorded in the KEL

Key Event Log (KEL)¶

The KEL is a hash-linked sequence of signed events:

Event type	Description
Inception	Creates the identity; commits to the first rotation key
Rotation	Replaces the active key; commits to the next rotation key
Interaction	Non-key-changing event (anchoring data to the log)

Each event is signed by the current key and references the previous event's SAID (Self-Addressing Identifier Digest), forming a tamper-evident chain.

The KEL is stored in Git at refs/keri/kel (legacy backend) or packed under refs/auths/registry (registry backend).

Security properties¶

Pre-commitment prevents key hijacking -- even if the current key is compromised, the attacker cannot rotate to their own key because they do not hold the pre-committed next key
Forward security -- rotating keys limits the window of compromise
Non-repudiation -- the KEL provides a tamper-evident history of all key changes
Commitment verification -- during rotation, the next key's public key is verified against the hash committed in the previous event; a mismatch aborts the rotation

Post-rotation checklist¶

Sign something and verify it round-trips: git commit --allow-empty -m test && auths verify HEAD
Update CI/CD secrets if they reference the old key alias
Verify the setup: auths doctor
Confirm the new key is active: auths id show