Rotate to replace a token's value in place, or revoke it to stop it working immediately
Rotation swaps the secret while keeping the identity; revocation kills the identity. Both take effect on the very next request that carries the old value.
Rotate#
POST /v1/service-account-tokens/:id/rotate generates a fresh sat_… value, overwrites the stored hash on the same row, and returns the new plaintext once. The token keeps its id, name, scopes, creation date, and activity history — dashboards and audits continue to refer to one credential. Because the hash is replaced rather than added alongside, there is no dual-validity window: deploy the new value to your client before or immediately after rotating, never long after. An unknown id answers Token not found.; a revoked token answers A revoked token cannot be rotated. Create a new one instead.
Revoke#
DELETE /v1/service-account-tokens/:id stamps revokedAt and leaves the row in place for history. Authentication ignores revoked tokens outright, so a leaked credential stops working the instant you call this — there is no grace period. The token still appears in listings (marked revoked) so you can see what existed.
Expected result#
Rotation for planned credential hygiene on a schedule; revocation for incidents. Pair either with the activity log to confirm calls stop (or continue under the same token id after a rotate) — see Review activity.