Rotating and revoking

Three operations on an existing key:

Rotate — issue a new key string. Optionally with a grace window during which the old string still authenticates.
Revoke — mark the key inactive. The next call returns 401.
Expiry — automatic deactivation at the expiresAtUtc set at mint time, if any.

Rotate

Rotation issues a new key string. The key's identity (name, project, environment) is unchanged. The dashboard reveals the new full key string exactly once.

With a grace window

When rotated with grace seconds N, the previous string remains valid for N seconds after rotation. Both strings authenticate during that window. After the window, the previous string stops working.

Without a grace window

Grace seconds 0 makes the swap immediate. The previous string stops working at the moment of rotation.

What rotation does not change

The key's name, project binding, environment, and dashboard id.
Historical RequestLog rows and ledger entries continue to attribute to the same key.

Revoke

Revoke marks the key as Revoked. From that moment, every call carrying the key returns 401 UNAUTHORIZED. There is no grace window on revoke.

A revoked key cannot be reactivated.

Expiry

If expiresAtUtc was set at mint time, the server stops accepting the key at that timestamp. The response shape is the same 401 UNAUTHORIZED as a revoked key.

Expiry is silent — there is no email or in-dashboard warning ahead of the deadline.