Skip to content

BYOK Key Versions Unreadable

URI: https://docs.ankatech.co/errors/byok-key-versions-unreadable
HTTP Status: 422 Unprocessable Entity

When you see this

The credential of a tenant's own key-protection backend (BYOK), checked when the declared backend is bound or submitted to rotate the credential of one, reached the declared key and passed the wrap and unwrap round trip, but it cannot read the state of the key or of its versions. The platform reads that state after every restore and upgrade, to check that the key-encryption keys the tenant's stored keys use are still usable, so a credential that cannot read it is refused.

Nothing was stored. On a bind, the backend stays declared and is not bound; on a rotation, the credential in force remains. The same answer comes back on the platform plane and on the tenant plane.

Submitting the same credential gives the same answer until the permission is granted, so the response is not retryable as it stands.

Common Causes

  • Google Cloud KMS: the credential lacks cloudkms.cryptoKeys.get or cloudkms.cryptoKeyVersions.list on the declared key. The role roles/cloudkms.cryptoKeyEncrypterDecrypter includes neither.
  • AWS KMS: the credential lacks kms:DescribeKey, or, for a key with imported key material (origin EXTERNAL), kms:ListKeyRotations.

Azure Key Vault and Managed HSM need no additional permission: the get key permission already required serves the read, and a credential without it is refused with this type.

Response Example

{
  "type": "https://docs.ankatech.co/errors/byok-key-versions-unreadable",
  "title": "BYOK Key Versions Unreadable",
  "status": 422,
  "detail": "The credential reached the declared key but cannot read the state of its versions. Grant it the permission to read the key's versions, then submit again. On a credential rotation, the current credential remains in force.",
  "instance": "/api/v3/admin/tenants/7d1c9b40-52e8-4a36-9f07-c3b81e6d240a/key-backend/byok/credential",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "5b2e8c14-9d3a-4f61-8a07-e4c92b1d6f38",
    "reason": "KEY_VERSIONS_UNREADABLE",
    "check": "KEY_STATE"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The response carries no Retry-After header.

Extension Values Meaning
reason KEY_VERSIONS_UNREADABLE The credential could not read the key's version or material list
check KEY_STATE The check that runs after a passed round trip and reads the key's state with the submitted credential

The body names the missing capability through its reason, never the key, the endpoint, the account or any credential field, and the credential you submitted is never logged or echoed. A refused rotation is recorded in the audit trail with the outcome key-versions-unreadable.

This type answers only a BYOK bind or credential rotation. The deployment backend, the ANKA-managed tiers and KEK operations answer a failure to read a key's versions with their own errors.

How to Resolve

  1. At the cloud provider, grant the credential the read permissions on the declared key: cloudkms.cryptoKeys.get and cloudkms.cryptoKeyVersions.list on Google Cloud KMS; kms:DescribeKey, plus kms:ListKeyRotations for a key with imported material, on AWS KMS; the key get permission on Azure Key Vault and Managed HSM.
  2. Bind the backend again, or submit the same credential again for a rotation. Nothing was changed: the tenant's declaration and the credential in force are exactly as they were.

The per-cloud client prerequisites of the key-protection backend documentation list every permission the platform needs, with why each is needed.

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