Overview — Secrets Rotation Runbook

Step-by-step runbooks for rotating the secrets that actually leak — database

passwords, API keys, cloud access keys, JWT signing keys, TLS certs, and OAuth

client secrets — without downtime. Each runbook uses the two-secret

(dual-key) pattern so you never have a window where the old secret is dead but

the new one isn't live yet.

The core pattern (applies to every secret)

Rotation that causes downtime is rotation nobody does. The fix is overlap:

1. Create the new secret alongside the old one.

2. Publish it to the secret store (both valid now).

3. Deploy consumers to accept BOTH old and new.

4. Cut over producers to emit/use the new secret.

5. Verify nothing uses the old one (logs/metrics).

6. Revoke the old secret.

Never delete before step 5. Never cut over before consumers accept both.

Runbooks included

• runbooks/database-password.md — rotate a DB user's password with a standby user.
• runbooks/cloud-access-key.md — rotate AWS/GCP/Azure keys (two-key overlap).
• runbooks/api-key.md — rotate a third-party or your-own API key.
• runbooks/jwt-signing-key.md — rotate a JWT/JWKS signing key with kid overlap.
• runbooks/tls-certificate.md — renew + roll a TLS cert with no handshake gap.
• runbooks/oauth-client-secret.md — rotate an OAuth client secret.

When to rotate

• On a schedule (30–90 days for keys, per policy).
• Immediately on suspected exposure (committed to git, leaked in logs, laptop lost).
• On employee offboarding for anything they could have seen.

Requirements

None to read. Provider CLIs for the applicable runbook.