Swap the key's secret IN PLACE and return the new plaintext in result.plaintext_token EXACTLY ONCE: hand it to the user, never log it, unrecoverable. Sid, name, permissions and expiry are unchanged. The previous secret stays valid until result.previous_token_expires_at (now plus grace_seconds, 24 hours by default; 0 = immediate cutover), so a config can be updated without downtime. Use when a secret leaks or before an offboarding. NOT idempotent: every call mints a brand-new secret. A revoked or expired key answers 409.

Contract:

• MCP tool rotate_api_key, registry package mcp.id/api_keys, mount id.access.
• Operation action, response envelope action.
• Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.