Skip to content

Tenant Backend Already Bound

URI: https://docs.ankatech.co/errors/tenant-backend-already-bound
HTTP Status: 409 Conflict

When you see this

A per-tenant bring-your-own-backend declare or change was attempted for a tenant that already holds key material. The immutability authority is the key-material-exists read against core-api: once the tenant has any key material, its key-material backend is not changed by a declare, because re-pointing the declaration would strand that material. The backend of a tenant that holds key material changes through a key custody move, which re-wraps every key of the tenant under the new backend's key-encryption key. The refusal happens before any credential is sealed and before any descriptor is mutated.

Common Causes

  • Declaring a different BYOK backend for a tenant that has already created at least one key.
  • Changing a tenant's existing BYOK declaration after its first key was wrapped.

This is the BYOK plane. On the managed-Edition plane an Edition change of a tenant that holds key material is not refused: it records a key custody move to the new Edition's tier. The deployment plane answers backend-already-bound; the deployment's own backend is never changed in place.

Response Example

{
  "type": "https://docs.ankatech.co/errors/tenant-backend-already-bound",
  "title": "Tenant Key-Material Backend Immutable",
  "status": 409,
  "detail": "This tenant already holds key material; its key-material backend changes only through a key custody move.",
  "instance": "/api/v3/admin/tenants/7d1c9b40-52e8-4a36-9f07-c3b81e6d240a/key-backend/byok",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "9c72e158-40ab-4d36-8e15-b3097fa25c64"
  }
}

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

How to Resolve

  1. Read the tenant's current declaration with GET /api/v3/admin/tenants/{tenantId}/key-backend/byok to confirm which backend is in force.
  2. If the declared backend is the intended one, no action is needed — the refusal protects the key material already wrapped under it.
  3. If a different backend is required, start a key custody move to it: POST /api/v3/admin/tenants/{tenantId}/key-custody/moves on the tenant plane, or, on a private-cloud or on-premise deployment, POST /api/v3/admin/platform/tenants/{tenantId}/key-custody/moves. Another key under the same provider account and credential moves online; another account, credential or backend runs as a maintenance window.
  4. A bind self-test never creates key material, so a tenant that has been bound but holds zero keys can still change its backend with a declare.

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