Skip to content

Key Reference Required

URI: https://docs.ankatech.co/errors/key-reference-required
HTTP Status: 422 Unprocessable Entity

When you see this

You declared a key-bound operation on an internal crypto use case without naming the key it applies to. The create contract refuses the request before anything is provisioned: the capability grant it would emit derives its wildcard-asset flag from the kid list being empty, so a key-bound operation reaching that point with no keyKid would authorize every asset in the tenant.

Common Causes

  • operations contains at least one key-bound operation and keyKid was omitted from the request body.
  • keyKid was sent as an empty or whitespace-only value by a caller that does not pass through request validation.
  • The operation set was changed to a key-bound one without adding the key reference alongside it.

Response Example

{
  "type": "https://docs.ankatech.co/errors/key-reference-required",
  "title": "Key Reference Required",
  "status": 422,
  "detail": "A key reference (keyKid) is required for the requested operations; key-bound operations cannot be authorized without naming the key they apply to.",
  "instance": "/api/v3/admin/tenants/2f1c9d84-6b2e-4d3a-9f57-0a1b2c3d4e5f/internal-crypto-use-cases",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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

How to Resolve

  1. Add keyKid naming the key the declared operations act on, and re-submit.
  2. If the use case genuinely binds to no tenant-owned key, declare only the interoperability or migration-data operations, which are not key-bound.
  3. Nothing was provisioned by the refused request, so no cleanup is required before retrying.

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