Skip to content

Key-Protection Declaration Not Valid For This Driver

URI: https://docs.ankatech.co/errors/key-backend-declaration-invalid
HTTP Status: 400 Bad Request

When you see this

A key-protection declaration in the driver form (driver, properties, secrets) was refused by the declared driver's descriptor. Nothing was written and nothing was contacted.

Each declarable-backend read publishes, per backend, the properties and the credential fields its driver accepts on that plane (properties and secrets of each entry). The declaration is checked against that descriptor before anything else happens, and the first name it refuses is reported:

extensions.reason Meaning
UNKNOWN the driver declares no such property or credential field, or no driver answers to the token
MISSING a property or credential field the plane requires is absent
MALFORMED the value breaks the property's type, pattern, maximum length or allowed values
NOT_ON_PLANE the property, or the driver itself, does not sit on this plane — for example a PKCS#11 token on a tenant BYOK plane
READ_ONLY the value is supplied by the service or derived by the driver, so a declaration never carries it — on a managed tier this covers every coordinate the tier's settings supply
NOT_APPLICABLE the property applies only while another property holds certain values (its visibleWhen), and the declaration does not hold them
ENDPOINT_REFUSED an endpoint this plane may not name: not HTTPS, an internal address, or, on a tenant BYOK plane, a host outside the backend vendor's domains

An endpoint is checked with the platform's HTTPS endpoint and internal-address rules under the plane's egress posture, then with the cloud backend endpoint policy and, on the tenant BYOK planes, against the domains of the backend's vendor.

Response Example

{
  "type": "https://docs.ankatech.co/errors/key-backend-declaration-invalid",
  "title": "Key-protection declaration is not valid for this driver",
  "status": 400,
  "detail": "The properties member 'keyId' is refused (MALFORMED).",
  "instance": "/api/v3/admin/platform/setup/backend/driver-declaration",
  "timestamp": 1760620800,
  "extensions": {
    "member": "properties",
    "field": "keyId",
    "reason": "MALFORMED",
    "requestId": "3b6e9a0c-71d2-4f58-9a3e-8c5d2b17f0a4"
  }
}

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

The problem carries three extensions of its own:

  • member — the part of the body the refused name belongs to: driver, properties or secrets;
  • field — the refused property or credential field, or driver for the token;
  • reason — one of the values in the table above.

It never carries a submitted value, and a credential field is never echoed. The refusal is audited on the plane's failure record with the reason DECLARATION_INVALID and the field name.

How to Resolve

  1. Read the plane's declarable-backend entry for the declared driver and compare the body with its properties and secrets: the names, required, pattern, maxLength, allowedValues, readOnly, plane and visibleWhen of each entry are the rules this check applies.
  2. Correct the named member and send the declaration again.

Operations that emit it

Method Endpoint
PUT /api/v3/admin/platform/setup/backend/driver-declaration
PUT /api/v3/admin/platform/key-backend/tiers/{tier}/driver-declaration
PUT /api/v3/admin/platform/tenants/{tenantId}/key-backend/byok/driver-declaration
PUT /api/v3/admin/tenants/{tenantId}/key-backend/byok/driver-declaration

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