BYOK Declared Key Unusable

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

When you see this

A new access credential submitted to rotate a tenant's own key-protection backend (BYOK) was checked against the key the tenant declared, and that key could not be found or addressed with it. The new credential was not stored, and the credential in force remains.

This is not a statement that the new credential is wrong. The key service reported that the declared key does not exist, the declaration could not be used with the new credential at all, or the declared security domain is absent. Replacing the credential again will not help until the declaration and the credential point at the same key. When the key service answered and refused the credential itself, the answer is BYOK Credential Self-Test Failed instead.

Submitting the same credential against the same declaration gives the same answer, so the response is not retryable as it stands.

Common Causes

• The declared key was deleted, or scheduled for deletion, at the cloud provider since it was declared.
• The new credential belongs to a different account, project or directory than the one that holds the declared key, so the key service answers that the key does not exist (KEY_ABSENT).
• The declaration cannot produce a working client with the new credential — for example a credential whose content does not fit the declared backend (DESCRIPTOR_INVALID).
• The security domain the declaration names is not present (SECURITY_DOMAIN_ABSENT).

Response Example

{
  "type": "https://docs.ankatech.co/errors/byok-declared-key-unusable",
  "title": "BYOK Declared Key Unusable",
  "status": 422,
  "detail": "The declared key could not be found or addressed with the new credential. Check that the declared key still exists and that the new credential belongs to the account that holds it. 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_ABSENT",
    "check": "EXISTING_MATERIAL"
  }
}

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

The body never names the key, the endpoint, the account or any credential field, and the credential you submitted is never logged or echoed. The refusal is recorded in the audit trail as credential-rotate-refused, the same entry a refused credential writes.

How to Resolve

1. Confirm at the cloud provider that the declared key still exists and is enabled.
2. Confirm that the new credential belongs to the account, project or directory that holds that key. With KEY_ABSENT, this is the most common cause when the key itself is intact.
3. With DESCRIPTOR_INVALID or SECURITY_DOMAIN_ABSENT, compare the new credential and the declared coordinates with the backend family the tenant declared.
4. Submit the corrected credential again. Nothing was changed: the credential in force, the tenant's declaration and its last recorded credential check are exactly as they were.

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