Secret rotation strategy: automated, scheduled, and emergency

Most teams do not rotate secrets. They intend to. The API key from the launch year is still in production, still valid, still present in eleven files. Rotation is deferred because it is disruptive: rotate a key and every consumer breaks until it is updated. So the security control that would limit the damage of every leak is the one that gets skipped. A workable rotation strategy has three tiers — automated, scheduled, and emergency — and each answers a different question.

Why rotation is hard

The mechanics are trivial: issue a new key, revoke the old one. The difficulty is consumers — CI pipelines, cron jobs, agents, third-party services, each holding a copy. If ten systems hold a key, rotation is a ten-system deployment. That is why leaked keys stay valid for months and why the breach report always includes the phrase “the key had been active since”.

Tier one: automated rotation

For anything with a supported API — cloud provider keys, database credentials, OAuth tokens — automate. Issue new credentials at the source on a cadence that matches risk, then propagate the new value to consumers. Automation only works if retrieval is centralized: when every consumer reads secrets from a single store, rotation is one write followed by propagation. If secrets are copied into per-system config files, there is nothing to automate — you have recreated the eleven-file problem in a new form.

OAuth deserves special mention. The RFC 8628 device flow, combined with auto-refresh and single-use refresh-token rotation, removes humans from the loop entirely: the client re-authenticates itself, the old refresh token is invalidated on first use, and a stolen token is a dead token by the time it is stolen. The same principle — short-lived credentials that replace themselves — is the right target for every tier.

Tier two: scheduled rotation

For credentials that cannot be automated — some third-party portals, shared accounts, legacy integrations — schedule it. Pick a recurring date, put it in a calendar, and treat the window as maintenance. Three details matter:

• Rotate during low traffic, not during the Friday afternoon rush.
• Allow a grace period where old and new credentials are both valid, so consumers that missed the memo do not hard-fail.
• Verify consumers after the switch and keep the verification results.

A schedule that lives only in your head is a wish, not a control.

Tier three: emergency rotation

Emergency rotation is the one that actually matters: a leak is confirmed, a repository went public, a contractor left. The runbook must be pre-written, not improvised at 2am. It needs three things. An inventory — every place the secret lives; the store is the source of truth only if consumers really read from it. An ordering — revoke first, then update consumers that break, then verify. And a communication path, because the people running the rotation and the people whose pipelines break are usually not the same. The worst emergency outcome is not downtime; it is rotating the wrong key and discovering consumers nobody listed.

The store makes all three tiers easier

Every tier shares one requirement: a single source of truth that consumers read at runtime. With that in place, rotation is a change to one record, and the tiers differ only in trigger and speed. Without it, every tier is a hunt.

trustless, a credential broker CLI for AI agents, is built around that idea: it reads an existing pass or Bitwarden store, and its OAuth device flow implements auto-refresh with single-use refresh-token rotation, never retrying an invalid grant — dead credentials fail fast instead of hammering the provider. The full command set is documented under commands.

If you revoked your oldest production key today, how many workflows would break — and do you know the answer without checking?