Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Tenant KMS Key Rotation

Rotation creates a new tenant master key version wrapped under your KMS key. New writes immediately use the new version; existing ciphertext stays readable because the retired version remains available for unwrap. A background rewrap job migrates existing data to the new version automatically.

​
What happens during rotation

  1. A new 32-byte master key is generated and wrapped using your KMS key → new active version
  2. The previous active version is moved to retired
  3. New encrypts (new secrets, new CA key versions, new DB passwords) use the new active version immediately
  4. Existing ciphertext wrapped by the retired version continues to unwrap successfully
  5. A background rewrap job is enqueued to re-encrypt all existing tenant data under the new active version

​
When to rotate

  • Suspected compromise of the old master key version
  • Scheduled compliance rotation (annual, quarterly — check your policy)
  • Post-breach seal/unseal cycle — rotate after any event where you were unsure of KMS security
  • KMS key rotation on the cloud provider side — rotate the KnoxCall master key after rotating the underlying KMS key so new wraps use the new KMS key version

​
How to rotate

​
Via admin UI

  1. Go to Settings → Security → Tenant KMS
  2. Click Rotate key
  3. Confirm the dialog — type the tenant slug if prompted

​
Via API

Rotation requires a step-up token with a 5-minute window. Obtain a fresh step-up token via POST /admin/auth/step-up immediately before calling rotate. 
curl -X POST https://api.knoxcall.com/admin/tenant-kms/rotate \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-KnoxCall-StepUp: $STEPUP_TOKEN"
Response: 
{
  "rotated": true,
  "new_version": 2,
  "rewrap_lease_id": 42
}
rewrap_lease_id is the identifier for the background rewrap job described below. It is null if the rewrap lease failed to issue — the rotation itself still succeeded in that case; contact support to trigger the rewrap manually.
Rotation is non-reversible. Once the old version is retired, you cannot make it active again. You can still decrypt existing data, but new writes will use the new version. If you revoke the old version later, anything written under it becomes permanently unreadable. Cannot be called while the tenant is sealed — unseal first.

​
Background rewrap

After rotation completes, KnoxCall immediately enqueues a tenant_rewrap background job. This job re-encrypts all existing tenant data under the new active master key version:
  • Processes 100 rows per batch (interleaved: 50 from secret_environment_configs, 50 from integration_configs)
  • Batches run every 5 seconds
  • The target_version is pinned at job creation time — even if another rotation occurs mid-flight, all rows processed by this job land on the same version (prevents split-version state across a rotation boundary)
  • Rows already on the target version are skipped and counted as complete
  • The lease expires after 7 days — if a persistent KMS error prevents rewrap from completing in that window, contact support
You can track rewrap progress via Automation → Agents in the admin UI. The old retired version remains available for decryption throughout the rewrap and beyond, until you explicitly revoke it.

​
Audit trail

Every rotation is logged in the critical audit chain:
Audit actionMeaning
byok.kms.rotateMaster key rotation initiated
The log entry includes new_version, wrap_method, rewrap_lease_id, and the IP that triggered it.

​
Key version lifecycle

ACTIVE (v2) ← current wrapping
RETIRED (v1) ← still decryptable, no new wraps
  ↓ (if explicitly revoked)
REVOKED (v1) ← cryptographic erasure — data is permanently unreadable
Revoking a retired version is a destructive, permanent action. Use it only when you need to guarantee that data written under that version can never be recovered — for example, data destruction per GDPR right-to-erasure.

​
Checking key versions

curl https://api.knoxcall.com/admin/tenant-kms \
  -H "Authorization: Bearer $KC_ADMIN_JWT"
The response keys array contains all versions: 
{
  "config": { ... },
  "keys": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "version": 2,
      "wrap_method": "customer_kms",
      "status": "active",
      "created_at": "2026-05-25T10:00:00Z",
      "retired_at": null
    },
    {
      "id": "a7c1d8f3-2e4b-4c6a-8d9e-1f3b5a7c9d2e",
      "version": 1,
      "wrap_method": "customer_kms",
      "status": "retired",
      "created_at": "2026-01-01T00:00:00Z",
      "retired_at": "2026-05-25T10:00:00Z"
    }
  ]
}

Sealed state and unseal

What happens if KMS becomes unreachable after rotation

Tenant master key concepts

Version lifecycle and cryptographic erasure background

Tenant KMS API reference

Rotate endpoint reference

Audit Logs

View the rotation audit trail