Secrets Rotation Workflow: Mermaid Flowchart

Secrets Rotation Workflow flowchart diagram

About Source

A secrets rotation workflow is the automated process of replacing cryptographic keys, API tokens, database passwords, and other credentials before they expire or are compromised — without causing service downtime.

How rotation works

Secrets rotation is triggered either on a schedule (e.g., rotate database passwords every 90 days) or by an event (suspected compromise, departing employee with access, security audit finding). Manual rotation is error-prone and causes outages; automated rotation is the reliable alternative.

The rotation process begins by generating a new secret value. For database passwords, this means issuing a new password to the database user. For API keys, it means calling the provider's API to generate a new credential pair. For TLS certificates, it means requesting a new certificate from the CA.

Before the old secret is deleted, the new secret must be distributed to all consumers without downtime. This is accomplished using a dual-active window: both the old and new secrets are valid simultaneously for a short overlap period. The secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager) stores the new version while keeping the previous version accessible.

Applications are updated to load the new secret version. In Kubernetes, this typically involves restarting pods so they mount the updated secret from the secrets store. In serverless environments, functions reload secrets from the manager on each cold start. The rotation workflow monitors each application's health checks during the transition to detect any connection failures caused by misconfigured secret paths.

Once all consumers have confirmed they are using the new secret version, the old secret is revoked and deleted. The rotation event and its completion timestamp are logged in the audit trail for compliance purposes.

Frequently asked questions

A secrets rotation workflow is the automated process of replacing cryptographic keys, API tokens, and database passwords before they expire or are compromised — without causing service downtime by using a dual-active window where both old and new secrets are valid simultaneously.

The rotation job generates a new secret, stores it alongside the old version in a secrets manager (Vault, AWS Secrets Manager), then updates all consuming applications to load the new version. Once health checks confirm all consumers have adopted the new secret, the old version is revoked and the audit log is updated.

Rotate secrets on a schedule (every 30–90 days depending on sensitivity) and on-demand after a suspected compromise or when a team member with access departs. Automated rotation is essential for high-security environments; manual rotation at scale is too error-prone and frequently causes outages.

mermaid

flowchart TD
    RotateTrigger[Rotation trigger: schedule or security event] --> GenerateSecret[Generate new secret value]
    GenerateSecret --> StoreNew[Store new secret version in secrets manager]
    StoreNew --> DualActive[Enable dual-active window for old and new versions]
    DualActive --> UpdateConsumers[Distribute new secret to all consumers]
    UpdateConsumers --> RestartApps[Restart or reload application pods]
    RestartApps --> HealthCheck[Monitor health checks during transition]
    HealthCheck --> HealthGate{All consumers healthy?}
    HealthGate -->|No| DiagnoseFailure[Diagnose secret path or format issue]
    DiagnoseFailure --> FixConsumer[Fix consumer configuration]
    FixConsumer --> HealthCheck
    HealthGate -->|Yes| VerifyNew[Verify all consumers use new secret version]
    VerifyNew --> RevokeOld[Revoke old secret version]
    RevokeOld --> DeleteOld[Delete old secret from secrets manager]
    DeleteOld --> AuditLog[Record rotation event in audit log]
    AuditLog --> ScheduleNext[Schedule next rotation]