Skip to content

HSM BYOK Unavailable On SaaS

URI: https://docs.ankatech.co/errors/pkcs11-byok-unavailable-in-saas
HTTP Status: 422 Unprocessable Entity

When you see this

A per-tenant bring-your-own-backend declare or bind selected a PKCS#11 HSM backend on a SaaS deployment. A PKCS#11 HSM requires a token bound to the deployment host, and a SaaS tenant cannot attach its own HSM to shared SaaS infrastructure, so the combination is refused. The request is syntactically valid — this is a policy refusal keyed on the deployment class and the backend class, not on your tenant's data.

Common Causes

  • Declaring softhsm, nshield, luna or cloudhsm as a per-tenant BYOK backend on a SaaS deployment.
  • Binding an existing declaration that names one of those backends on a SaaS deployment.

Response Example

{
  "type": "https://docs.ankatech.co/errors/pkcs11-byok-unavailable-in-saas",
  "title": "HSM BYOK Unavailable On SaaS",
  "status": 422,
  "detail": "Per-tenant HSM (PKCS#11) BYOK is not available on this SaaS deployment; use a Cloud KMS backend, or bring your own HSM on a private-cloud or on-premise deployment.",
  "instance": "/api/v3/admin/tenants/7d1c9b40-52e8-4a36-9f07-c3b81e6d240a/key-backend/byok",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "cf30a687-b512-4e94-8d76-21e40f9c5b8a"
  }
}

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

How to Resolve

  1. Declare a Cloud KMS backend instead. Per-tenant Cloud KMS BYOK is admissible on SaaS, because each call injects the tenant's own sealed credential.
  2. If a hardware HSM is a requirement, run on a private-cloud or on-premise deployment, where the customer owns the host and every supported backend remains admissible.
  3. Rehearse a declaration with POST /api/v3/admin/tenants/{tenantId}/key-backend/byok/validate before committing it, so the deployment's policy is settled before the write.

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