Skip to main content
CID222 Docs

Issue and manage customer licences

Operate the hub-only owner licence console to issue, renew, revoke and re-download signed customer licence files without exposing the signing key.

  • Version: 0.4
  • Role: admin_user
  • Type: task

License Management is the vendor-hub owner console. It issues, renews, revokes and retrieves customer .lic files through an issuer sidecar. It is intentionally absent from customer appliances even though the code is present in the shared image.

Danger

Do not try to enable this page on a customer appliance. The owner guard requires the provisioned hub, its issuer token and a healthy sidecar that can reach the signing key and registry. On every other box the protected routes answer 404 so the signing surface is indistinguishable from a feature that does not exist.

What do I need?

Role
admin_user

Prerequisites

  • CID_LICENSE_ISSUER=true is set only on the vendor hub.
  • CID_LICENSE_ISSUER_TOKEN matches the issuer sidecar bearer token.
  • The issuer sidecar health check confirms the private key and registry are present.
  • The update-channel revocation file is writable before you revoke a licence.

Issue a licence

Open License Management on the hub

The dashboard first calls GET /admin/license-admin/config. The page appears only when owner_console is true. A customer box returning false is working as designed.

Select the customer and package

Package and feature choices come from the issuer sidecar's tier catalogue. Do not recreate the package list from memory; the same image can issue a newer feature set than an old browser tab.

Set the dates, limits and notes

Confirm the installation identity and every commercial limit. Notes are stored in the registry with the authenticated operator's username, which the server supplies rather than trusting a username from the request body.

Issue and save the file

The response contains lic, license_id and filename. Save the downloaded .lic, send it through the agreed customer channel and retain the registry id in the handoff record.

Renew instead of issuing a replacement

Renew the existing registry row when the commercial identity continues. The history panel keeps every licence for a customer, including who issued or revoked it and why. Issuing a new licence because a file was misplaced changes the registry's account of what was sold; use Download on the historical row when has_lic is true.

A re-download returns the original signed envelope byte for byte. It is refused when the licence is revoked or predates stored envelopes. Renew the latter; never mint a second file under the same license_id.

Revoke a licence

Revocation records the authenticated operator and refreshes the update channel's revocations.json. Confirm the customer, licence id and reason before continuing. A revoked file is never available for re-download.

Warning

An air-gapped appliance cannot learn about a new hub revocation until it receives an updated revocation set through its supported offline process. Destroying or recalling the file alone does not change a running disconnected box.

Verify

  1. GET /admin/license-admin/config returns owner_console: true on the hub and false elsewhere.
  2. Tier choices match the current issuer catalogue, including add-ons.
  3. Issue a test licence and verify its registry row carries your authenticated username and notes.
  4. Re-download it and compare its checksum with the original file.
  5. Revoke the test licence; confirm the history records who revoked it and that download is disabled.
  6. Confirm the revocation appears in the channel data before treating the action as distributed.

If it fails

  • 404 on a protected route means the deployment is not a healthy, provisioned owner console. Check the issuer flag, token and sidecar health; do not weaken the owner-console guard.
  • 502 means the gateway could not complete the sidecar request. Inspect the sidecar health and its access to the registry and key without copying the private key into the gateway container.
  • 409 on re-download means the row is revoked or has no stored envelope. The message distinguishes the cases; renewal is the supported path for an old row.
  • If issue succeeds but no file reaches the browser, retrieve the same row from its history rather than issuing again.

Last updated on

On this page