Error Reference

Tenant KMS endpoints return errors in one of two shapes. The onboard and probe failures return a human-readable message in error (with an optional details field):

{ "error": "KMS access denied. Check that the IAM/RBAC grant gives KnoxCall both Encrypt and Decrypt on this key.", "details": "..." }

The unseal and rotate endpoints return a machine-readable code in error plus a message:

{ "error": "not_sealed", "message": "Tenant is not currently sealed" }

This table is non-exhaustive — it lists the common failures. Validation errors (missing 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`, `POST /admin/tenant-kms/revert`)

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>, "action_scope": "tenant.kms", "allowed_methods": ["passkey", "2fa"] }`	Re-verify with a second factor within the last `max_age_minutes`, passing the response’s `action_scope` as `action_scope`, and retry: `POST /auth/2fa/verify-step-up` (authenticator-app code), `POST /auth/passkey/verify-step-up` (passkey), 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

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)

Overview

Workload Identity

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Error Reference

Error reference

Onboard / probe failures (`POST /admin/tenant-kms`)

Step-up required (`POST /admin/tenant-kms/unseal`, `POST /admin/tenant-kms/rotate`, `POST /admin/tenant-kms/revert`)

Unseal / rotate failures

​Error reference

​Onboard / probe failures (POST /admin/tenant-kms)

​Step-up required (POST /admin/tenant-kms/unseal, POST /admin/tenant-kms/rotate, POST /admin/tenant-kms/revert)

​Unseal / rotate failures

Error reference

Onboard / probe failures (`POST /admin/tenant-kms`)

Step-up required (`POST /admin/tenant-kms/unseal`, `POST /admin/tenant-kms/rotate`, `POST /admin/tenant-kms/revert`)

Unseal / rotate failures