Rotate an API key

Rotate an API key by invalidating the old secret and generating a new one.

Important:

• The old key will be immediately invalidated
• A new key will be generated with the same settings (name, role, expiration, etc.)
• The new key will only be shown once in the response
• If the key carries a scoped role its owner can no longer be assigned (e.g. the owner was demoted, or the role was deleted), rotation is refused with 403 (API_KEY_ROLE_NO_LONGER_ASSIGNABLE) rather than re-minting the elevated role — revoke the key instead.
• A key with no entity scope (issued before keys were entity-bound) cannot be re-minted: rotation is refused with 409 (API_KEY_ENTITY_UNBOUND) — revoke it and create a replacement.
• Under API-key authentication, the acting key may rotate the owner's other keys only in the tenant it is pinned to; elsewhere the request is refused with 403.
• The replacement inherits the key's remaining lifetime and name, and a key can only be minted with at least 1 day of lifetime and a name of at most 32 characters. A key that no longer satisfies either is refused with 409 (API_KEY_REMAINING_LIFETIME_TOO_SHORT or API_KEY_NAME_TOO_LONG) before anything changes — create a new key instead. An already-expired key is refused the same way.
• Rotation never leaves you without a key: the original is retired only once the replacement is scoped and the rotation recorded, in one unit, so if any step fails the original stays live and the error is returned.
• If the key is suspended or reactivated while it is being rotated, the rotation is rolled back and refused with 409 (API_KEY_STATE_CHANGED) so that change is not overwritten — check the key's status and retry.

Use this when you suspect a key may have been compromised or as part of regular security practices.