Key Protection Backend Not Bound

URI: https://docs.ankatech.co/errors/backend-not-bound
HTTP Status: 503 Service Unavailable

When you see this

An operation reached the deployment-plane key-protection seam while this environment's key-protection backend is not bound and ready. Deployment secret custody seals under the deployment KEK, so with no bound backend nothing can be sealed and the operation fails closed: no envelope row is written, and nothing is stored unsealed as a fallback.

Common Causes

• The environment is still in SETUP_REQUIRED — the backend has been declared but first-run provisioning has not bound it. Binding is a console step for softhsm and for the five Cloud KMS tokens; for luna, nshield and cloudhsm the console withholds the activation control and the bind is issued on the host with init-hsm.sh <env> --activate.
• No key-protection backend is available to this instance, so no deployment KEK can be resolved.
• The deployment KEK could not be created or fetched from the backend.
• The secret-custody token layer is missing, uninitialised or unreachable, or a generated KEK did not persist.

Response Example

{
  "type": "https://docs.ankatech.co/errors/backend-not-bound",
  "title": "Key protection backend not bound",
  "status": 503,
  "detail": "The key-protection backend for this environment is not bound and ready. Please retry once it has been provisioned.",
  "instance": "/api/v3/admin/platform/observability/backends",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "a71e0c33-5b48-4f9e-8c21-b6d40e7a2915"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

On the three token-signing-key operations (/api/v3/admin/platform/token-signing-keys, see Admin API — Platform Token Signing Keys) and the three projection-signing-key operations (/api/v3/admin/platform/projection-signing-keys, see Admin API — Platform Projection Signing Keys) the response also carries Retry-After: 30: there the deployment backend is the custody root of the signing key set, and the answer matches token-signing-key-custody-unavailable and projection-signing-key-custody-unavailable. Binding completes on an operator action rather than on a timer, so the value is a polling interval. Every other operation answers without Retry-After.

How to Resolve

1. Check first-run state with GET /api/v3/admin/platform/setup/status.
2. Read the response's declaredBackend and go to the route it names. The console offers the bind control only where the certification manifest reports no host-preparation blocker for that backend — today that is softhsm — and for the five Cloud KMS tokens, which are configured, credentialled and activated by one submit. On those routes bind from Platform Settings → Cryptography & Trust → HSM / Cloud KMS, which calls POST /api/v3/admin/platform/setup/backend/activate.
3. Where the manifest reports a blocker — luna, nshield and cloudhsm report HARDWARE — the console withholds that control and shows the host command in its place, so the bind is issued on the environment host with init-hsm.sh <env> --activate. That command reaches the same activate operation. Then finish with Complete setup in the console: activate completes first-run provisioning itself on every family, but deliberately not when the caller is the environment host, so a host-issued bind leaves the environment on BINDING until the running services carry the bound configuration, then on BOUND_PENDING_COMPLETE, and completes with POST /api/v3/admin/platform/setup/complete.
4. Retry the original request once the backend reports bound. The refused call persisted nothing, so the retry is safe.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.