Skip to content

Key Coordinate Is Not Valid For This Backend

URI: https://docs.ankatech.co/errors/key-backend-coordinate-malformed
HTTP Status: 422 Unprocessable Entity

When you see this

The keyId you submitted does not parse as a key coordinate for the backend family you declared. The request was refused before anything was written: no declaration was recorded, no coordinates were stored, and nothing was contacted.

Every backend takes the same wire member — keyId — but each family reads it under its own grammar, and the grammar is the vendor's own rather than a rule this platform invented:

Declared backend What keyId must be Parsed by
aws-kms a KMS key ARN carrying a region and an account id the AWS SDK's ARN parser
gcp-kms, gcp-kms-hsm projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey} Google's own CryptoKeyName parser
azure-kv, azure-kv-mhsm a key name inside the vault named by endpoint no published grammar — never refused for this cause
PKCS#11 backends a token key label no published grammar — never refused for this cause

A family with no published grammar cannot raise this problem at all. That is not leniency: absence of a grammar means there is nothing to check, and the platform says so rather than inventing a rule the vendor does not have.

Common Causes

  • A Cloud KMS resource path with a missing or misspelled segment — keyRing for keyRings, a truncated path, or the key's version path where the CryptoKey path was expected.
  • A key ARN pasted without its region or account id, or an ARN for a different AWS service.
  • The right coordinate submitted under the wrong backend token — an ARN declared as gcp-kms, or a resource path declared as aws-kms.
  • An Azure vault URL pasted into keyId. The vault URL is the endpoint; keyId is the key name.

How to Resolve

  1. Read extensions.backendType in the response — it names the family whose grammar was applied.
  2. Read detail, which states the shape the family requires. It never echoes the value you submitted, and neither does the server-side log entry.
  3. Correct the coordinate, or correct the declared backend if the coordinate was right and the token was wrong, and resubmit.

The value is never reflected back. A key ARN names an AWS account id and a Cloud KMS resource path names a project — so neither the response nor the log line repeats what you sent. detail describes the required form; extensions.field is always keyId.

The pre-commit check gives the same answer without writing. POST /api/v3/admin/platform/setup/backend/validate reports a FAILED / DESCRIPTOR_INVALID verdict — as an HTTP 200, because the question was answered — with KEY_ID_GRAMMAR_PARSED among the checks that ran and no TRANSPORT_PROBE, so a coordinate that cannot name a key never causes an outbound connection.

Where it is raised

  • PUT /api/v3/admin/platform/setup/backend/configuration — the deployment plane
  • PUT /api/v3/admin/tenants/{tenantId}/key-backend/byok and its platform-plane twin — per-tenant BYOK