Skip to content

Allowlist Change Affects Declared Backends

URI: https://docs.ankatech.co/errors/key-backend-allowlist-affects-tenants
HTTP Status: 422 Unprocessable Entity

When you see this

A platform operator submitted a BYOK backend allowlist that excludes a key-protection backend one or more tenants have already declared, and the write did not carry a matching acknowledgement. The refusal is raised before anything is persisted, so the current allowlist is still in force while you read the blast radius. extensions.affectedTenantCount carries the cardinality — never a tenant identity, backend, endpoint or key id.

Common Causes

  • Narrowing ankasecure.key-protection.byok.allowed-backends without supplying acknowledgeAffectedTenants.
  • Supplying an acknowledgement that does not equal the affected count — for example one computed from a stale read, so the count has moved since it was displayed.

Response Example

{
  "type": "https://docs.ankatech.co/errors/key-backend-allowlist-affects-tenants",
  "title": "Allowlist Change Affects Declared Backends",
  "status": 422,
  "detail": "The proposed allowlist excludes a key-protection backend that tenants have already declared. Those tenants keep operating on it — only new declares and binds are refused. Re-submit with acknowledgeAffectedTenants set to the reported count to confirm.",
  "instance": "/api/v3/admin/platform/settings/ankasecure.key-protection.byok.allowed-backends",
  "timestamp": 1730000000,
  "extensions": {
    "affectedTenantCount": 3,
    "requestId": "2f6b8d05-91ea-4c37-bf40-7c1d5e83a962"
  }
}

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

How to Resolve

  1. Read extensions.affectedTenantCount — that is how many tenants' existing declarations the proposed allowlist would put out of conformance.
  2. Re-submit the same allowlist with acknowledgeAffectedTenants set to exactly that number. The check is an equality, so re-read the current count rather than resending a constant.
  3. If the impact is not acceptable, submit a wider allowlist instead. Resetting the setting to its default is always permitted and never requires an acknowledgement, because restoring the unbound policy admits every backend.

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