Skip to content

Key-Material Backend Bind Verification Failed

URI: https://docs.ankatech.co/errors/tenant-backend-bind-selftest-failed
HTTP Status: 503 Service Unavailable

When you see this

The per-tenant BYOK bind self-test failed: the ephemeral wrap/unwrap round trip against the tenant's declared key-material backend did not complete or did not round-trip. The bind therefore does not advance to active — the tenant's declaration reverts to pending-bind so the backend configuration or credential can be corrected and the bind retried. The response carries a Retry-After header.

Common Causes

  • The declared backend rejected the tenant's credential, or the credential lacks the permissions the round trip needs.
  • The backend endpoint was unreachable or timed out during the round trip.
  • The unwrap did not reproduce what the wrap produced, so the round trip did not verify.

The probe is deliberately ephemeral and non-tenant: it creates no key material and never makes the tenant's key-material-exists read true, so a tenant that fails this test can still change its declared backend.

Response Example

{
  "type": "https://docs.ankatech.co/errors/tenant-backend-bind-selftest-failed",
  "title": "Key-Material Backend Bind Verification Failed",
  "status": 503,
  "detail": "The key-material backend bind verification did not complete; retry the operation shortly.",
  "instance": "/api/v3/admin/tenants/7d1c9b40-52e8-4a36-9f07-c3b81e6d240a/key-backend/byok/bind",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "62f0a7d4-1c98-4b53-a06e-d75381c9e2f0"
  }
}

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

How to Resolve

  1. Run POST /api/v3/admin/tenants/{tenantId}/key-backend/byok/test — that surface answers a verdict for every backend condition and names what the bind could not do.
  2. Correct the backend coordinates or the tenant credential, submitting a new credential with PATCH /api/v3/admin/tenants/{tenantId}/key-backend/byok/credential if needed.
  3. Re-run the bind. The declaration is still pending-bind, so no state has to be unwound first; the underlying cause is in the server logs and is never rendered in the response.

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