Testing a Key Rollover: Changing Signing Keys Without Breaking Sign-In

Signing keys cannot last forever. They may need replacement because of a schedule, a suspected exposure, or a move to a stronger algorithm, and the replacement must happen without locking users out. A key rollover is the managed process of introducing a new signing key, moving traffic to it, and retiring the old one, and it only works safely if the old and new keys overlap for a time. The Key Rollover Test helps you check the stages of a rollover using the key details and token samples you paste in, in your browser, without contacting your servers. It tests the material you supply; it cannot change your live key configuration, and it cannot prove that every verifier in your system has picked up the new key.

The overlap is the heart of the process. Tokens signed with the old key remain valid until they expire, and those tokens must still verify after the new key appears, or users holding them will be rejected mid-session. At the same time, newly issued tokens should use the new key, so that the old key's usage drains away over time. A verifier that knows both keys during the overlap handles both generations correctly, while a verifier that only knows one will fail one generation or the other. The rollover test checks exactly this: can the system verify tokens under each key, and does the new key appear where verifiers look for it?

How it works

A rollover usually runs in stages. First, publish the new public key alongside the old one, so verifiers can discover it before it is used. Second, start signing new tokens with the new key while still accepting the old key for verification. Third, monitor verification failures and token ages, watching for verifiers that still reject the new key or still depend on the old one. Fourth, once old-key tokens have expired and failures have settled, stop signing with the old key, and finally remove it from publication. Each stage deserves its own check, because a failure caught at the publishing stage is a configuration fix, while the same failure caught after the old key is removed is an outage.

Timing and caching decide whether the stages work. Verifiers often cache key sets for minutes or hours, so a newly published key may not be visible to every verifier immediately, and a removed key may linger in caches after removal. The overlap period must be longer than the longest cache lifetime plus the longest token lifetime, or some tokens will fall into a gap where no verifier accepts them. That arithmetic, not optimism, sets the length of the overlap, and it is why rushed rollovers fail more often than slow ones.

Where it goes wrong

The most common rollover error is removing the old key before its tokens have expired, which instantly invalidates every session still holding one. Another is publishing the new key in one place but not in every place verifiers read from, so some verifiers never learn it. A third is testing only the happy path, signing a fresh token with the new key, while never testing an old-key token during the overlap, which is the case that actually breaks users. Also avoid performing a rollover with production keys pasted into a test tool; test with sample keys and sample tokens, and keep real keys inside their home systems.

Worked example

Worked example with sample values. Suppose tokens live for 60 minutes and verifiers cache key sets for 30 minutes. The minimum safe overlap is 60 plus 30, which is 90 minutes, and a cautious plan doubles the margin to 180 minutes, which is 3 hours. During a sample rollover, you test 10 tokens: 5 signed with the old key and 5 with the new key. Before publishing the new key, the old-key tokens verify 5 out of 5, which is 100 percent, and the new-key tokens verify 0 out of 5, which is 0 percent. After publishing, both groups verify 5 out of 5, giving 10 out of 10, which is 100 percent overall. After retiring the old key, the new-key tokens still verify 5 out of 5, while the old-key tokens, now expired, verify 0 out of 5, which is the intended result. These are sample values for illustration, not a live rollover, and the counts show how each stage has its own expected result.

Mistakes to avoid

One mistake is rolling over every system at once instead of one service at a time, which turns a contained failure into a platform-wide one. Another is forgetting scheduled jobs and background services, which often hold long-lived tokens and are the last to move to the new key. A third is skipping the rollback plan: if the new key proves faulty, you need a documented way back to the old key while it is still published, not a scramble after it is gone. Write the rollback steps before you start, not during the incident.

Putting it into practice

Run rollovers as a rehearsed routine. Publish the new key, wait out the cache lifetime, test old and new tokens against every verifier you can reach, switch signing to the new key, monitor failures for a full token lifetime, and only then retire the old key. Record the key identifiers, the dates of each stage, and the failure counts, so the next rollover starts from evidence rather than memory. A rollover that feels uneventful is a successful one; excitement during a rollover is almost never good news.

Related tools and reading: the JWT Decoder and the JWK and JWKS Viewer cover neighbouring checks that pair naturally with this one, and the guide at [/blog/jwt-decoder-guide/] extends the same topic with further background and examples for readers who want to go deeper.

Key points

• Rollover replaces a signing key without breaking verification
• Old and new keys must overlap while tokens transition
• Test both keys at every stage before retiring the old one
• A failed rollover is usually a cache or timing problem

In short: A key rollover works when old and new keys overlap long enough to cover token lifetimes plus cache lifetimes. Publish first, sign with the new key second, monitor third, and retire the old key last. Test both keys at every stage.

One habit ties all of this together: re-check after every change. A result is only as current as the input it was run on, so a fix, a redesign, or a new version of the underlying material deserves a fresh run rather than reliance on an old report. Keep the previous result alongside the new one, note what changed between them, and treat any new finding as a question to investigate rather than a verdict to accept or dismiss. That loop of checking, fixing, re-checking and recording is what turns a one-off test into a reliable routine, and it costs far less time than debugging a problem that a second check would have caught early.