Every organisation has a rotation policy. Most have keys that have not been rotated in years. The gap is not negligence — it is that rotation without a two-key overlap means downtime, and a procedure that causes downtime gets postponed indefinitely.
The interval adjusts to reality
The planner starts from sensitivity, then adjusts for the things that determine whether you will actually do it:
- Manual rotation relaxes the interval by 50%. A 30-day manual schedule across a team is not sustainable; a 45-day one might be. A schedule nobody meets provides no security and considerable false comfort.
- More than five consumers relaxes it by 25%, because every rotation becomes a coordinated deploy.
These adjustments are deliberate. The honest recommendation is the one you will follow.
Automate first, then tighten
If you take one thing from the output: the first investment is the automation, not the calendar entry.
An automated 90-day rotation beats an aspirational 30-day manual one every time, because it happens. Once it is automated, shortening the interval is a configuration change.
The two-key overlap
The only rotation procedure that avoids downtime:
- Issue the new key. Both are now valid.
- Deploy the new key to every consumer.
- Watch the old key's last-used timestamp in the provider dashboard.
- Revoke the old key when it stops moving, and no earlier than the overlap window.
- Confirm the old key now returns 401.
Step 1 requires your API to accept two keys simultaneously. If it cannot, build that first — it is the difference between rotation being routine and rotation being an outage.
Maximum exposure
The readout combines the interval and the overlap into a single number: how long a silently compromised key stays valid. That is the figure worth arguing about in a design review, because it is the actual security property. A 90-day interval with a 30-day overlap gives an attacker 120 days.
Per-consumer keys remove the constraint entirely
Sharing one key across services is what makes rotation a coordinated deploy. Issue one key per consumer and each rotates independently, on its own schedule, with no coordination and no shared blast radius. It costs nothing at issuance time and it changes rotation from a project into a routine operation.
Frequently asked questions
How often should I rotate?
The interval this tool produces, based on what the key can reach and whether you have automated it. But rotation frequency matters much less than rotation *capability*: a system that can rotate in five minutes when a key leaks is far safer than one that rotates on schedule but takes two days in an emergency.
Is rotation still necessary if nothing has leaked?
Yes, for two reasons. It bounds the damage from a leak you have not detected — which is most of them. And it proves the procedure works, so that when you do need to rotate urgently, you are not discovering the problems then.
What if a consumer is offline during the overlap?
Extend the overlap to cover the longest expected downtime. That is exactly what the overlap window is sizing, and it is why very short overlaps cause incidents.
How do I know when the old key stopped being used?
Every major provider exposes a last-used timestamp. Check it before revoking rather than trusting your deployment records — there is usually one consumer nobody remembered.