Rotate and revoke a key

Two operations, and they are for different situations.

Rotate replaces a key on schedule, with no interruption. Revoke pulls one key immediately, because it leaked.

Rotation: append, prove, then expire

Checking a connection tells you whether it worked, disconnect is the whole-connection version, and the control-plane seam is why the order matters as much as it does.

Never replace. The order is the entire safety property.

1. Append. The new public key arrives in a call signed with the current one. Your Worker verifies with the key it already trusts and appends the new one. Both keys are now valid.
2. Prove. A real call, signed with the new key, confirmed to succeed.
3. Expire. Only then does the old key get an end date — and that call must itself be signed with the successor. Naming a live key is not proof that you can sign with it; only signing with it is.

Reverse those, or swap without proving, and a bad rotation locks the client out permanently with no authenticated path back. You would re-run the connect by hand.

pithy dashboard rotate --env prod

$ pithy dashboard rotate --env prod
Rotated prod. New key cpk_2026_08.
cpk_2026_07 is still live. Expire it from your management client once it has proven cpk_2026_08.
Done.

That second line is the point of the command. The CLI does steps 1 and 2. Step 3 belongs to the management client, once it has proven the successor from its own infrastructure — which is the only place that fact can be established.

Two live keys is normal, not an exception

It is what the versioned key array is for.

A stale key costs nothing. Expiring one that turns out to be the only working credential costs the connection. Those are not symmetric risks, and the design is arranged around the asymmetry.

Revocation: immediate, unilateral, local

pithy dashboard revoke-key --env prod --key-id cpk_2026_07 --yes

It stamps one key revoked in your D1 and tells nobody. That is what immediate and unilateral has to mean — a revocation that depends on the other side acknowledging it is not a revocation.

Revocation ignores any end date the key already had and takes effect at once.

It is the narrow instrument beside disconnect’s blunt one. A client that leaked a single key does not need the whole connection rebuilt, its scopes re-chosen and its address re-registered.

It will take your last live key

If you ask it to. The connection is then denying every call, and the command says so plainly.

That is deliberate: somebody holding a leaked key must never be told they have to keep trusting it until a replacement is arranged. Denying everything is a recoverable state; a live leaked credential is not.

Which one to reach for

How old is the key?

pithy dashboard status --env prod

Every registered key comes back with its age in whole days, live or superseded — the number a rotation policy is read against — plus when it became valid, when it expires if it does, and when it was revoked if it was.

Nothing here imposes a rotation cadence. It reports the number so you can.

Rotating your own client’s key

The three calls are yours to make, in the same order. connect --public-key registers a first key and refuses a successor while one is live, naming the call that appends one — it has no private half to sign with, and doing it for you would take the registration out of your own audit trail.