Error reference
Tenant KMS endpoints return errors in one of two shapes. The onboard and probe failures return a human-readable message inerror (with an optional details field):
error plus a message:
provider, kms_key_ref, malformed config) also return 400 with a descriptive error message.
Onboard / probe failures (POST /admin/tenant-kms)
These return { error: "<message>", details?: "<string>" }.
| Status | error message | Meaning |
|---|---|---|
400 | KMS access denied. Check that the IAM/RBAC grant gives KnoxCall both Encrypt and Decrypt on this key. | The probe encrypt/decrypt round-trip was denied by your KMS IAM/RBAC policy |
400 | Field "<name>" is not permitted in tenant KMS config. ... | config contained a blocked static-credential field (access key, secret key, client secret, private key, service-account key, etc.) — use STS/WIF/SA-impersonation instead |
400 | KMS probe roundtrip mismatch — refusing to onboard a key we cannot reliably decrypt with. | The wrap+unwrap probe did not return the original plaintext |
400 | KMS probe failed. | The probe failed for another reason (see details) |
401 | authentication required | No authenticated session |
400 | X-Tenant-ID header required | X-Tenant-ID header missing |
403 | <reason> | Caller is not an owner/admin of the tenant |
500 | Failed to persist BYOK configuration. | The configuration probe passed but persisting it failed (see details) |
502 | KMS provider unreachable during probe. Try again in a minute. | KnoxCall could not reach the KMS provider during the probe |
Step-up required (POST /admin/tenant-kms/unseal, POST /admin/tenant-kms/rotate)
These endpoints require a recent step-up verification. When one is missing or expired:
| Status | Response | Meaning |
|---|---|---|
403 | { "error": "Recent step-up verification required for this action", "requires_step_up": true, "max_age_minutes": <n> } | Re-verify step-up (e.g. POST /auth/2fa/verify-step-up or POST /auth/passkey/verify-step-up) within the last max_age_minutes and retry |
Unseal / rotate failures
These return{ error: "<code>", message: "<string>" }.
| Status | Code | Meaning |
|---|---|---|
404 | no_kms_config | No customer KMS configured for this tenant (unseal only) |
404 | no_active_key | No active master key found — required for rotation |
409 | not_sealed | Tenant is not currently sealed (unseal only) |
409 | sealed | Cannot rotate while sealed — unseal first |
500 | provider_resolve_failed | KMS provider could not be constructed from the stored config (unseal) |
500 | provision_failed | Provisioning a new tenant master key failed (rotate) |
502 | unseal_failed | Unseal roundtrip failed — KMS still unreachable or access still denied (includes a reason field) |