Rotate Master Key

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 via POST /auth/2fa/verify-step-up (TOTP), POST /auth/passkey/verify-step-up (passkey), or the email fallback (POST /auth/step-up/email-challenge then POST /auth/step-up/verify-email); check GET /auth/step-up/status to confirm a valid step-up exists. 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 }.

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

{
  "rotated": true,
  "new_version": 2,
  "rewrap_lease_id": 42
}

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).

curl -X POST https://admin.knoxcall.com/admin/tenant-kms/rotate \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID"

resp = requests.post(
    "https://admin.knoxcall.com/admin/tenant-kms/rotate",
    headers={
        "Authorization": f"Bearer {KC_ADMIN_JWT}",
        "X-Tenant-ID": KC_TENANT_ID,
    },
)
resp.raise_for_status()
print(resp.json()["new_version"])  # 2

const resp = await fetch("https://admin.knoxcall.com/admin/tenant-kms/rotate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KC_ADMIN_JWT}`,
    "X-Tenant-ID": KC_TENANT_ID,
  },
});
const { rotated, new_version, rewrap_lease_id } = await resp.json();

Unseal

Error Reference

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

POST /admin/tenant-kms/rotate

Response

​POST /admin/tenant-kms/rotate

​Response

POST /admin/tenant-kms/rotate

Response