Skip to main content

​
POST /admin/tenant-kms/rotate

Rotate the tenant master key. Creates a new 32-byte master key wrapped under your customer KMS key, sets it as the active version, and retires the current active version. A background rewrap job immediately begins re-encrypting existing tenant data under the new version. Auth: Authorization: Bearer <session jwt> + X-Tenant-ID. Requires an owner/admin session. This endpoint requires a recent step-up verification (re-authentication) performed within the last 5 minutes by the signed-in user. No step-up header or token is sent on this request — the server checks for a recent, unused verification tied to your session. To create one, re-authenticate with a second factor, passing "action_scope": "tenant.kms" in the body: POST /auth/2fa/verify-step-up (authenticator-app code), POST /auth/passkey/verify-step-up (passkey, challenge from POST /auth/passkey/authenticate-options), or POST /auth/2fa/webauthn/verify-step-up (security key or passkey, challenge from POST /auth/2fa/webauthn/step-up-options). An emailed code does not satisfy this gate. GET /auth/step-up/status reports unscoped verifications only, so it does not show a tenant.kms one. If none is present, the request returns 403 with { "error": "Recent step-up verification required for this action", "requires_step_up": true, "max_age_minutes": 5, "action_scope": "tenant.kms", "allowed_methods": ["passkey", "2fa"] }.
Rotation is non-reversible. The old version becomes retired and cannot be made active again. Data encrypted under the old version remains decryptable so that existing tenant data can still be read while the background rewrap job completes.
Cannot be called while the tenant is sealed — unseal first.

​
Response

rewrap_lease_id identifies the background rewrap job. This job processes 100 rows per batch at 5-second intervals, re-encrypting all existing tenant secrets under new_version. The old version remains available for decryption until the rewrap completes. rewrap_lease_id is null if the rewrap lease failed to issue (the rotation itself succeeded — contact support to trigger rewrap manually).