Skip to content

License Signing Key Unknown

URI: https://docs.ankatech.co/errors/license-signing-key-unknown
HTTP Status: 422 Unprocessable Entity

When you see this

The license artifact names, in signature.kid, a signing key that the running release does not trust. The signature was not checked, and nothing was stored.

Every release of the licence server carries a fixed set of ANKATech license-signing public keys, each addressed by its key identifier (kid, a thumbprint of the key pair). The set is part of the image; no configuration, environment variable or request adds a key to it. ANKATech rotates its signing key by shipping a release that adds the new key's kid to the set, so a license signed under a newer key is refused by a release that predates it.

Common Causes

  • A license signed under a newer ANKATech signing key, imported into a release that does not yet trust that key.
  • A license signed under a key that a later release removed from its trusted set.
  • An artifact whose signature.kid was edited. An edit that names a key the release does not trust is refused here; an edit that names another trusted key is refused as license-artifact-invalid, because the kid is part of the bytes both signatures cover.

Response Example

{
  "type": "https://docs.ankatech.co/errors/license-signing-key-unknown",
  "title": "License signing key unknown",
  "status": 422,
  "detail": "The license artifact is signed under a key this release does not trust. Ask ANKATech to re-issue the license, or upgrade to a release that trusts its signing key.",
  "instance": "/api/v3/admin/platform/license/import",
  "extensions": { "requestId": "6f8a0c2e-4b5d-4e7f-9a1b-3c5e7a9b1d46" }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The detail does not echo the kid the artifact presented.

Raised by the License Server, relayed by the Admin API

The import is POST /api/v3/admin/platform/license/import on the Admin API, which forwards the artifact to the licence server over a service-to-service call; the licence server is the only validator of the artifact and raises this refusal. The Admin API relays its type, title, detail and status unchanged and sets its own instance and extensions.requestId. Correlate a request by extensions.requestId.

How to Resolve

Do not edit the artifact. Contact ANKATech support with:

  1. The extensions.requestId from the failed import's problem body.
  2. The signature.kid value from the license file.
  3. The release the installation runs.

ANKATech either re-issues the license under a key your release trusts, or tells you which release to upgrade to.

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

* restricted content — see higher-tier documentation