Secrets and Credential Rotation Checklist

A credential rotation checklist for API keys, database passwords and tokens: find every consumer, rotate with no downtime, revoke the old secret and verify it.

Typical schedule per rotation, or when a secret leaks
The checklist 5 sections, 18 items
Variables {{secret_name}} {{reason}}
Start from CI

Use this template Free, no credit card. Imports the checklist into your Runbook organization.

Use this checklist when you rotate an API key, database password, signing key, cloud access key or other credential. That happens on a schedule, when someone with access leaves, and urgently when a secret has leaked into a repository, a log or a chat message. The steps are the same; only the speed changes.

Who owns it

The owner of the system that uses the secret runs the rotation. For shared credentials, such as a payment provider key used by several services, one person coordinates and the owners of each consumer confirm their part. Adapt this to your jurisdiction; it is a practical checklist, not legal advice.

Common pitfalls

Revoking first, then discovering consumers. Find every service, cron job and laptop script that uses the secret before you revoke the old one. Otherwise you cause your own outage.
Deleting the leaked commit and calling it done. Once a secret is pushed, assume it is compromised. Rotate it, then clean up history if you want.
Rotation without overlap. Where the provider allows two active keys, add the new one, switch consumers, then revoke the old one.
Not checking for use of the old key. Review the provider's access logs for use of the leaked secret between the leak and the revocation.

Start this run from your secret scanner or pipeline through POST /api/v1/runs, so every leak gets a documented response.

The checklist: Rotate {{secret_name}} ({{reason}})

Prepare

Record the trigger ({{reason}}) and, for a leak, when and where the secret was first exposed
The exposure time sets the window you need to check in the provider's access logs later.
Identify the system that issues {{secret_name}} and who administers it
List every consumer: services, CI pipelines, cron jobs, scripts and developer machines
Search your secret store, CI variables, infrastructure code and repositories for the secret name.
Check whether the provider supports two active credentials at the same time
Plan the order of updates and agree a time if a short outage is unavoidable

Rotate

Create the new credential with the minimum permissions needed
Store the new value in the secret manager (e.g. Vault, AWS Secrets Manager, 1Password)
Update every consumer to use the new credential
Restart or redeploy consumers that read secrets only at startup
Verify each consumer works with the new credential

Revoke and verify

Revoke or delete the old credential at the provider
Confirm nothing still uses the old credential by checking errors and provider logs
Review provider access logs for suspicious use of the old credential optional
Required after a leak. Look at the time between the leak and the revocation.

If the secret leaked

Remove the secret from the repository, log, ticket or chat where it appeared optional
Rewrite git history or ask the hosting platform to purge cached views optional
Start the incident or data breach procedure if the secret was used by someone else optional

Close

Update the secret inventory with the rotation date and next due date
Create tickets to prevent repeats, such as pre-commit secret scanning

Checklist as Markdown

# Rotate {{secret_name}} ({{reason}})

## Prepare
- [ ] Record the trigger ({{reason}}) and, for a leak, when and where the secret was first exposed
  The exposure time sets the window you need to check in the provider's access logs later.
- [ ] Identify the system that issues {{secret_name}} and who administers it
- [ ] List every consumer: services, CI pipelines, cron jobs, scripts and developer machines
  Search your secret store, CI variables, infrastructure code and repositories for the secret name.
- [ ] Check whether the provider supports two active credentials at the same time
- [ ] Plan the order of updates and agree a time if a short outage is unavoidable

## Rotate
- [ ] Create the new credential with the minimum permissions needed
- [ ] Store the new value in the secret manager (e.g. Vault, AWS Secrets Manager, 1Password)
- [ ] Update every consumer to use the new credential
- [ ] Restart or redeploy consumers that read secrets only at startup
- [ ] Verify each consumer works with the new credential

## Revoke and verify
- [ ] Revoke or delete the old credential at the provider
- [ ] Confirm nothing still uses the old credential by checking errors and provider logs
- [ ] Review provider access logs for suspicious use of the old credential (optional)
  Required after a leak. Look at the time between the leak and the revocation.

## If the secret leaked
- [ ] Remove the secret from the repository, log, ticket or chat where it appeared (optional)
- [ ] Rewrite git history or ask the hosting platform to purge cached views (optional)
- [ ] Start the incident or data breach procedure if the secret was used by someone else (optional)

## Close
- [ ] Update the secret inventory with the rotation date and next due date
- [ ] Create tickets to prevent repeats, such as pre-commit secret scanning

Start this checklist from your pipeline

When a secret scanner flags a leak, POST /api/v1/runs with template "Rotate {{secret_name}} ({{reason}})" and reason set to leak.

curl -X POST https://runbook.metastic.ch/api/v1/runs \
  -H "Authorization: Bearer $RUNBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "Rotate {{secret_name}} ({{reason}})", "variables": {"secret_name": "…", "reason": "…"}}'

See the API and the GitHub Action

Frequently asked questions

How often should API keys and credentials be rotated?

There is no single right interval. Rotate immediately when a secret leaks or when someone with access leaves, and rotate long-lived, high-privilege credentials on a regular schedule that your policy defines. Short-lived credentials, such as tokens issued through workload identity, reduce the need for manual rotation.

How do I rotate a secret without downtime?

Use overlap. Create the new credential while the old one still works, update and verify every consumer, then revoke the old one. If the provider only allows one active credential, schedule a short window and update consumers in a planned order.

What should I do when a secret is committed to git?

Treat it as compromised, even if the repository is private or the commit was removed quickly. Rotate the secret first, check the provider's logs for misuse, then clean the history if needed. Add secret scanning to stop the next one.

Updated 2026-11-04