Rotate credentials like a cutover, not a chore.

The reminder is not the plan

Someone gets a calendar ping. A vault entry ages out. A vendor email says the API key expires next week. The team treats it like password hygiene: generate a new value, paste it somewhere, hope the old one dies quietly. What actually happens is a partial flip. One worker still has the old key. A cron job still has the old key. A partner webhook still has the old key. Traffic fails in the worst place—the path you forgot—while the dashboard you were watching stays green.

A rotation is a cutover. Cutover means two values can be true for a while, then one stops being true on purpose, with a named person who can reverse the step if the new value does not work. Chore means one person updates a string and hopes.

This note is the TWIMCO Secret Rotation Cutover Card: one page for one credential. Fill it before you mint the new value. It is the asset. There is no published generator. Copy the fields into your runbook and leave blanks blank. Blank is a finding.

You do not need a client story to make the card useful. The pattern shows up anywhere a web application or integration holds a key that other systems call with. When the work is distributing and verifying live credentials across callers, the scoping home is web applications. Keep the card about your credential.

What the card forces you to name

Fill one card per credential. “All API keys” is not a card. Start with the secret that, if it stops working for ten minutes, costs money, trust, or a partner’s patience.

Credential. Name it the way an operator would: payment webhook signing key, warehouse SFTP password, marketplace OAuth client secret. Add the systems that currently hold a copy. If you cannot list the copies, you are not ready to rotate.

Blast radius. What fails if the old value stops being accepted before callers move. Name the caller paths, not a severity label. “Checkout capture” and “nightly catalog pull” are useful. “High” is not.

Mint path. Who may create the new value, in which store, and how the new value is delivered to the people who will install it. A secret pasted into chat is already a second problem.

Dual-accept window. The period during which both old and new are valid at the verifier. Write the start and end you intend, and who may shorten or extend it. If the vendor cannot dual-accept, write that honestly and design a freeze-and-flip instead of pretending.

Flip order. The sequence of callers that move to the new value. Put the least painful caller first when you can. Put the path you cannot monitor last only if you have a reason—and write the reason.

Probe. The check that proves a caller is using the new value before you retire the old one. A log line, a header, a vault version. “We deployed” is not a probe.

Retire. How the old value is revoked, and what you watch for twenty minutes after. Revoke is a step with an owner, not a hope that expiry does the work.

Rollback owner. The role who may put the old value back into service if the new one fails, and the condition that triggers that call. “Someone in Slack” leaves the line incomplete.

Evidence. What you keep: timestamps for mint, first dual-accept, each flip, retire, and any rollback. Do not put the secret value into the evidence. The card records the path, not the key.

That field set is the TWIMCO Secret Rotation Cutover Card. Another team can tell you to rotate secrets quarterly. They do not have this cutover shape tied to your callers.

Dual-accept, then flip on purpose

Most rotation failures are unfinished sentences.

The new key is minted and installed in one place. Other callers still use the old key. Someone revokes the old key because the ticket said “rotate.” The forgotten caller fails. Dual-accept exists so revoke happens after probes, not after a feeling that you are done.

The dual-accept window is shorter than the human schedule. A partner said they would update “this week.” Your window closes Tuesday. Their update lands Thursday. The card’s window line is where you compare vendor capability with how slow real callers move. If you do not know the slowest caller, write “unknown” and treat that as a block on retiring.

The flip is unordered. Three services move “whenever.” One of them still holds the old value in an environment variable that a deploy overwrote last month and a secret mount never replaced. Flip order plus probe is how you notice that before retire.

Rollback is undiscussed. The new key works in staging and fails in production because of an IP allowlist or a second factor the mint path skipped. Nobody is named to restore the old key, and the vault already deleted it. The rollback-owner line is done only when the old value can still be restored for the window you named—or when you explicitly accept that rollback means a full re-mint under incident rules.

When you fill the card from a dry run, mark evidence: shown, described, or not shown. Do not upgrade “not shown” because the vault UI looked polished. These are delivery-shaped composites from web and integration work, not a claim about any vendor’s outage rate.

Refuse the rotation that only updates one place

A few shapes keep showing up. They are composites, not client outcomes.

Someone rotates the value in the vault and never updates the worker that still reads an old environment file. The probe was “vault version changed.” The card’s copy list and flip order would have caught that.

Someone emails a partner the new key and marks the ticket done. The partner has three environments. Two still use the old key. Dual-accept and a partner probe belong on the card before retire.

Someone sets the old key to expire automatically and goes home. Expiry is not a controlled flip. If a job runs across the expiry boundary, you get a partial night of failures with nobody watching the retire step.

Someone pastes the new secret into a ticket “so the next person has it.” The mint path failed the confidentiality line. Fix the delivery path before you argue about window length.

If you recognize one of these, complete the card and then change the systems to match it. Completing the card and leaving the habit intact only makes the next outage easier to narrate.

Put this into practice

1. Pick one credential that would hurt if it died mid-day. Put that name on a TWIMCO Secret Rotation Cutover Card.
2. List every copy and every caller. Unknown stays unknown—and blocks retire.
3. Fill dual-accept window, flip order, probe, retire, and rollback owner. Schedule the window when someone is awake.
4. Dry-run mint and dual-accept in a non-production twin if you have one. Score what you can show, not what the runbook wishes.
5. If the gap is the application surface that holds and distributes the secret, bring the card into a scoping conversation for web applications.

A rotation without a dual-accept window is a cutover you refused to schedule.

Related work: Sutton|Place.