Rotate Write Token

Rotate a write token: expire the existing token and create a new one atomically.

By default the old token stops working immediately. Pass grace_period_hours to keep it working while the replacement is deployed, which is what a credential baked into a running deployment needs, since that deployment has to be rolled out before the old token can stop. During that window both tokens work, and previous_token_expires_at says when that stops being true.

A grace period only ever shortens the outgoing token's life. If it was already going to expire before the window ran out, that earlier expiry stands: this route retires a credential, so it never hands one more time than it was granted.

The replacement is minted inside the rotation rather than here, because what it has to look like (whether it is public, its scopes) is a property of the token being rotated and is not known until that row has been read.

A token belonging to a frontend application is refused, as it already is by the expire and revoke routes beside this one. Those credentials live in a shipped browser bundle, and replacing one is two steps taken on the customer's own timing: add a second token, redeploy, then revoke the first. A grace period would instead retire a published credential on a clock this API sets.