Rotate an API token's secret (new secret revealed once)

Token callers: a pc_live_ token may only rotate a token whose scopes it holds itself -- otherwise 403 FORBIDDEN TOKEN_SCOPE_MISSING (missingTokenScopes), nothing rotated -- and only one inside its own fences (expires no later, allowlist inside its own ipAllowlist), otherwise 403 FORBIDDEN TOKEN_FENCE_EXCEEDED. Rotates the secret material of an API token ("Rotate" / "Rotate now" in the UI). A new secret is minted and returned exactly once in this response; the old secret remains valid for a 24-hour grace period so running clients can be migrated without an outage, after which it is invalidated. The token record itself (id, name, scopes, allowlist) is unchanged apart from its prefix reflecting the new material. During the grace period the old secret is subject to exactly the same status, expiry, IP-allowlist and scope rules. Only one previous secret is kept: rotating again inside the grace window invalidates the older secret immediately; revoking or deleting the token invalidates both secrets at once. Validation: the token must exist and be visible in the active scope (NOT_FOUND otherwise); the current status must permit rotation — only ACTIVE tokens can rotate, EXPIRED/REVOKED tokens are rejected with CONFLICT (409); the caller must hold a token-management role (owner|admin|contributor) or the request fails with FORBIDDEN. Async & state: Asynchronous grace-window rotation; returns 202 with the rotation result — the token in its transitional dual-secret state, the new secret (one-time reveal, never retrievable again), and oldSecretValidUntil marking the end of the 24h grace window. The rotation reaches its terminal state when the old secret is invalidated; resource.updated SSE frames with kind: iam.api_token report the prefix change and the grace-window expiry. Errors: 401 unauthenticated; 403 caller lacks token-management permission; 404 unknown or out-of-scope token; 409 token is not ACTIVE (expired or revoked) and cannot rotate; 500 on backend failure. Idempotency/Concurrency: Idempotency-Key is optional (recommended); a replay with the same key returns the original 202 body — including the originally minted secret — instead of rotating twice. This operation does not check If-Match; a sent one is ignored.

Step-up: from a console session whose account has two-factor authentication, the factor must have been verified in the last 5 minutes, otherwise 403 MFA_STEP_UP_REQUIRED (verify with POST /auth/step-up, then retry). An API token is not asked; a service-account key is refused (403 INTERACTIVE_SESSION_REQUIRED: a service-account key never performs an IAM write).