API key states reference

This page describes the three ApiKey.status values, what each means, and what actions are available from each state.

Status values

Status	Meaning	Available actions
`active`	The key is valid and can authenticate API requests	Rotate, Revoke
`revoked`	An admin explicitly disabled the key — terminal and irreversible. API requests using this token return `401`.	None (the row is kept for audit history)
`expired`	The key’s `expiresAt` date has passed (a system-side transition, never an admin action). API requests return `401`.	None (issue a new key)

The ApiKey.status enum has exactly these three values. There is no “suspended” or “paused” state.

Token masking

The full API key token (mg_<env>_<32 base32 characters>) is returned by api_keys_create and api_keys_rotate once only, in that response. Every subsequent read — including api_keys_list — returns only the 8-character prefix (for example, abcd1234••••). The masking is intentional, not a gap.

Rotation overlap

When you rotate an active key, the new token becomes active immediately and the old token remains valid for seven days (ApiKeyRotateResponse.previousKeyExpiresAt). This window gives you time to update your integration before the old token expires. After seven days, the old token transitions to expired automatically.

Rotating a revoked or expired key returns 409 conflict.invalid_state. Issue a new key instead.

Expiry forewarning

The API keys list shows “Expires in N days” for any active key approaching its expiresAt. Keys with lastUsedAt: null that have not been used for a long time show “Never used” — these are candidates for revocation under a least-privilege hygiene policy.

Revoked key visibility

Revoked keys remain visible in the API keys list, greyed out with their revokedAt timestamp. They are not deleted — the history is preserved for audit purposes.