How to rotate API keys safely

Rotation is easy to describe and hard to ship without downtime: someone always forgets the cron job, the old laptop, or the third-party webhook still signed with the previous secret. This checklist is order-of-operations first.

1. Golden sequence

  1. Inventory every place the secret lives (CI, prod, staging, laptops, serverless, partner configs).
  2. Issue the new credential with narrow scope (least privilege).
  3. Deploy new values everywhere before revoking the old one (overlap window).
  4. Verify traffic succeeds (synthetic checks, logs).
  5. Revoke the old credential.
  6. Document rotation date and owner.

Never revoke first unless you know 100% the key is actively abused — even then, have a rollback contact with the vendor.

2. Stripe-style signing secrets (webhooks)

Stripe uses webhook signing secrets per endpoint. Rotation pattern:

  1. Add second endpoint or use vendor rotation UI if they support dual secrets.
  2. Update your verifier to accept both signatures during migration.
  3. Flip dashboards to new secret; then remove old.

Stripe docs: Webhook signatures (verify current UI flows).

3. AWS access keys (humans and CI)

Prefer eliminating long-lived keys:

  • OIDC for GitHub Actions → IAM role (GitHub AWS OIDC).
  • IAM Roles for EC2/ECS/Lambda.

If you must rotate static keys:

  1. Create new key for same IAM user (max two keys) or new user with same policy.
  2. Update every consumer.
  3. Disable old key; monitor CloudTrail / errors.
  4. Delete old key.

AWS guidance: Rotate access keys.

4. GitHub Personal Access Tokens (PAT)

  1. Generate new PAT with minimum scopes (read:packages, etc.).
  2. Update GitHub Actions secrets / local vault (PassStore).
  3. Run a test workflow.
  4. Revoke old PAT in GitHub settings.

GitHub: Managing your personal access tokens.

5. Database passwords

See dedicated playbook: recover from exposed database credentials — rotation often requires connection pool drains and failover planning.

6. Developer laptops

After rotation, purge old values from:

  • Local .env files (often forgotten).
  • PassStore entries (archive old version with date suffix).
  • Password managers with stale copies.

7. If rotation is because of a leak

Start with I accidentally committed an API key — revoke beats Git history rewriting for immediate risk reduction.

Related