Secrets management and rotation
Credential storage, access, and automated rotation workflow.
Every service needs secrets: database passwords, API keys, TLS certificates, and signing keys. Hardcoding them is a security disaster — they end up in source control, logs, and every developer's machine. Centralized secret management and automated rotation are how mature teams prevent credential leaks and limit the blast radius when one does happen.
This template maps the complete secrets lifecycle: storing credentials in a vault, controlling who can access them, automatically rotating them on schedule, and verifying that services can use the new credentials before revoking the old ones. It includes the critical fallback path — what happens when a rotation fails and you need to rollback.
When to use this template
- Security audit — walk through this diagram with your team and your auditor to show how secrets are stored, rotated, and audited. Fill in the actual vault technology (Vault, AWS Secrets Manager, etc.).
- Onboarding new services — show teams that any new service must support dynamic secret rotation. Use this diagram to explain why they can't just read a secret once on startup.
- Incident post-mortem — if a credential leaked, trace through this diagram to see which step failed and why rotation didn't catch it sooner.
How to adapt it
Customize it to your infrastructure and add your vault technology:
- Name your vault — replace "Store in vault" with "Store in AWS Secrets Manager" or "Vault by HashiCorp".
- Add notification channels — after "Notify services", add branches for Slack alerts, PagerDuty, and service restart orchestration.
- Add grace periods — between "Generate new secret" and "Revoke old secret", add a node for a 24-hour grace period with monitoring.
- Add certificate expiry — for TLS certificates specifically, add a decision: "Expires in 30 days?" to trigger proactive renewal before the hard deadline.
Visual edits regenerate clean code, so you can map your exact secrets workflow.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[Secrets exist] --> B{Secret type?}
B -->|API keys| C[Store in vault]
B -->|Database passwords| C
B -->|Certificates| C
C --> D[Access control: who can read?]
D --> E[Rotate on schedule]
E --> F{Rotation due?}
F -->|No| G[Continue using current secret]
F -->|Yes| H[Generate new secret]
H --> I[Update vault]
I --> J[Notify services]
J --> K[Services fetch new secret]
K --> L[Verify new secret works]
L --> M{Test pass?}
M -->|No| N[Rollback to old secret]
N --> O[Alert on-call]
M -->|Yes| P[Revoke old secret]
P --> Q[Log rotation event]
Q --> G
Frequently asked questions
- Why do I need to rotate secrets regularly?
- Secrets have a limited lifetime. If a key is leaked, compromised, or left in an old repository, rotation limits the damage window. Regular rotation (e.g., every 90 days) means any leaked key will eventually expire, and you're not storing credentials in the same place forever. It's a defense-in-depth practice: even if one key is found, your services keep working because they've already switched to a new one.
- How do I rotate secrets without downtime?
- The key is supporting multiple secrets at once. Before revoking the old key, deploy the new one alongside it. Let services use the new key for a period (usually hours to days) while the old one still works. Monitor for errors, then revoke the old key. This way, there's no moment when services have no valid credentials — rotation is a window, not a switch.
- What secrets should I store in a vault versus environment variables?
- Store ALL secrets in a vault (e.g., HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) — never hardcode them or rely on environment variables alone. Use environment variables only as a way for services to reference the vault URL and their own identity (so they can fetch secrets on startup). The vault is the source of truth; env vars are just pointers.
- How do I audit secret access?
- A vault logs every secret read and every rotation. Audit trails should show who requested which secret, when, and from where. If a compromise is suspected, review the logs to find when the secret was last used legitimately and when it might have been accessed by an attacker. This data is critical for post-incident investigation.
Related templates
Network topology diagram
Internet, regions, load balancers, subnets, and security boundaries.
Role-based access control decision
Authorization logic: user roles, permissions, and resource access checks.
Auto-scaling decision tree
CPU, memory, request volume, and cost trade-off decisions.