Your hub ships verification keys in each consumer's configuration file — how do you rotate the signing key without a flag day?

Several hundred subscriber newsrooms hold the hub's public verification key in a configuration file that was shipped to them. Nothing they run asks the hub for a newer one. That single fact turns a key rollover from a change the issuer schedules into a change several hundred other organisations have to make, which is why "we will just rotate at the weekend" is a flag day with better marketing. ## What makes this rotation different When consumers fetch verification keys from somewhere the issuer controls, the issuer owns the clock: make the new key available, wait out the consumers' refresh interval, then start signing. When the key arrives out of band, the issuer owns none of the clock. The window is bounded by your slowest subscriber's release process, which may be quarterly, and no deployment of yours shortens it. Two things follow at once: - **You need an inventory.** Rotation without a list of who holds which key is not a plan, it is an announcement. If you cannot enumerate consumers, the first deliverable of the rotation project is the list, not the key. - **The overlap is a consumer-side capability, not a document you publish.** If a subscriber's software can hold only one verification key, no schedule saves you — the change is simultaneous by construction. The real work of the first rotation is shipping every consumer a version that can hold two. ## The sequence 1. **Ship accept-both.** A consumer release that treats verification keys as a set and accepts a token signed by any member. Nothing is rotated yet; you are only buying the ability to rotate later. 2. **Distribute the new public key, still unused.** It sits in the set alongside the current one. Because you are not signing with it, a consumer that has it early loses nothing and a consumer that has it late has not broken anything. 3. **Measure adoption.** See below. This is the step that takes months and the step people skip. 4. **Canary the signing cutover.** Sign a small, reversible share of tokens with the new key and watch pull-failure rates and support volume. Ramp only if both stay flat. 5. **Cut over fully**, then **retire the old key** once the longest-lived token signed with it has passed its `exp`. That last step is measured in minutes and is the only short part of the whole schedule, though it is the part people picture when they hear "overlap window". ## Measuring adoption when you cannot see inside a consumer - **Version telemetry you already have.** Subscribers identify their client on every pull. Map client version to the key set that version shipped with, and adoption becomes a query you can run daily. - **An explicit acknowledgement.** Have the consumer report a short fingerprint of the verification keys it holds as part of a routine request or an operational report. It is the only signal that reflects the configuration actually loaded rather than the version notionally installed. - **The canary as measurement, not just as caution.** Signing one per cent of tokens with the new key tells you what no inventory can: whether the keys are really loaded in production. - **The honest admission.** If none of these is available, say plainly to whoever owns the subscriber contract that the choice is between a coordinated flag day and never rotating. That sentence is the deliverable; quietly hoping is not. ## Sizing the window The overlap must be at least the consumer adoption time, plus the longest lifetime of any token signed with the retiring key, plus a margin for clock differences between the hub and its consumers. In an out-of-band world the first term is measured in months and the second in minutes, so adoption dominates by orders of magnitude — which is exactly the intuition that a published-key-set world inverts, and why people who have only rotated in that world underestimate this one badly. ## Making the next rotation yours Treat the flag-day risk as a defect to design out, not a fact of life: - **Publish verification keys somewhere consumers fetch them,** and require refreshing as a condition of the feed, so the next rollover is bounded by a refresh interval you set. - **Put a deprecation clause in the subscriber contract** naming the notice period for a key change, so the slowest consumer has a contractual ceiling rather than an open-ended veto. - **Rotate on a schedule when nothing is wrong.** A rollover path that has never been exercised is not a path, and the first time you need it will be the compromise, under a clock, with the inventory half-built. The verifier's half of all this — how a consumer stores the set, when it refreshes, and what it does when it cannot — is the consumer's design problem and is decided on the other side of this boundary. The issuer's job is the schedule, the measurement and the retirement date.