Skip to content

Key Reference Not Found

URI: https://docs.ankatech.co/errors/key-reference-not-found
HTTP Status: 404 Not Found

When you see this

A read of a key record named a key that the caller's tenant does not hold, or that the caller may not see. Three Admin API reads answer it:

  • GET /api/v3/admin/tenants/{tenantId}/keys/{kid}/record (operation getKeyRecord, scope admin.keys.read);
  • GET /api/v3/admin/tenants/{tenantId}/keys/{kid}/record/versions (operation listKeyRecordVersions, scope admin.tenant.keys.materials.read);
  • GET /api/v3/admin/tenants/{tenantId}/key-references/{referenceType}/{referenceId} (operation resolveKeyReference, scope admin.keys.read).

The three cases below are one answer: the same type, title, status and fixed detail, with instance the request URI you sent. Nothing in the body depends on which case it was, so the response does not tell which identifiers are real.

Common Causes

  • The Key ID, key identity or material version id does not exist in the tenant in the path.
  • It belongs to another tenant: a reference resolves only within the tenant in the path, so a link copied from another tenant's audit trail never resolves here.
  • The key exists, but none of its versions is of an algorithm family this installation offers.

A destroyed key keeps its Key ID for good and is not one of these while one of its versions is of a family this installation offers: getKeyRecord answers its record with destroyedAt set, and resolveKeyReference answers keyState DESTROYED.

Response Example

{
  "type": "https://docs.ankatech.co/errors/key-reference-not-found",
  "title": "Key Reference Not Found",
  "status": 404,
  "detail": "No key of this tenant matches the reference.",
  "instance": "/api/v3/admin/tenants/3e7f1a2b-6c4d-4e8f-9a1b-2c3d4e5f6a7b/keys/payments-signing-mldsa/record"
}

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

How to Resolve

  1. Check that the tenant in the path is the tenant the key or the audit record belongs to.
  2. For resolveKeyReference, check that referenceType matches the identifier: key-identity for a key's identity (keyIdentity on crypto audit records), key-material for a material version's id.
  3. List the tenant's keys (GET /api/v3/admin/tenants/{tenantId}/keys) to find the Key ID.

See Key records and key references*.

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

* restricted content — see higher-tier documentation