License Status

Purpose

Every AI API Mapper installation runs under a license file issued by Coded Projects: an evaluation license, or a commercial license for your edition. The Runtime reads that file, checks it, and reports what it found. The Portal shows the result as a yellow bar at the top of every screen, including the sign-in page.

A license problem never stops the platform. A missing, invalid or expired license does not block a sign-in, a tool call or a restart: the platform keeps serving, records the condition in the audit trail, and shows the bar until the license is fixed. The license is how your entitlement is recorded, and the bar is how the platform tells you honestly where you stand.

What The Yellow Bar Means

The bar updates by itself: when a license expires, or a new file is installed, the Portal shows the new state within seconds, without a sign-out or a page reload.

The License Page

Every signed-in user can open License from the bottom of the sidebar, beside the version numbers. It shows the license state, edition, validity dates and days remaining, together with how many Runtime instances are reporting their license and whether they all run the same one. It never shows whom the license was issued to.

Global administrators (sessions holding tenants:read@global, as for the Tenants screen) also see View each instance's license. That screen lists every Runtime instance with the license it runs: the licensee, the license number, the edition, the expiry date, the signing key, the number of Runtime instances the contract covers, and when the instance last reported. The contract count is shown for reference only and is never enforced.

Several Runtime Instances

Each Runtime instance reads its own /license/license.json, so in a deployment with several instances they can disagree. Usually this means one instance started without the license folder mounted, or with an old file.

• The Portal shows the worst state among the instances. If one of three instances has no license, the bar says "No license installed", even though the other two are licensed, because that one needs fixing.
• The License page says when instances disagree. On the per-instance screen, each instance that differs from the shown state is highlighted.
• Fix it by installing the same license file on every instance. Each one picks it up within a minute.
• Instances report at startup, whenever their license changes, and every five minutes. An instance that has not reported for 15 minutes (scaled down or stopped) is shown as Not reporting and no longer counts. After 7 days it disappears from the list.
• The sign-in page cannot ask the Portal and shows what one instance says. After sign-in, the bar shows the worst state across all instances.

Reason Codes

When the bar says a license is not valid, the reason in brackets is one of these.

Installing Or Replacing A License

The Runtime reads the license from /license/license.json inside its container. In a Docker Compose installation that folder is a read-only bind mount of a folder on the host; the compose file names it with LICENSE_DIR:

runtime-host:
  volumes:
    - ${LICENSE_DIR:-./license}:/license:ro

1. Check the new file first, with the Runtime image you are running, so a bad file never replaces a good one:

   docker run --rm -v "/path/to/folder/with/the/new/file:/license:ro" \
     <registry>/codedprojects/ai-apimapper-runtime-host:<tag> --verify-license /license/license.json
   

   It prints the same status the Portal would show and exits with 0 for a valid license, 2 for an expired one, and 3 for a missing or invalid one. It starts nothing and needs no database.

2. Replace the file in the license folder, keeping the name license.json. Copy it to a temporary name first and rename it over the old one, so the Runtime never reads a half-written file.

3. Wait up to a minute. The Runtime checks the file every 60 seconds and picks up the new one without a restart. The Portal's bar changes as soon as it does.

The file name you received (for example ACME-SpA-LIC-….license) does not matter; its content does. Rename it to license.json.

To move from an evaluation to a commercial license, replace the evaluation file with the commercial one in the same way. Nothing else changes.

Checking The Status Directly

The same status is available without signing in:

curl https://<your-gateway>/runtime/license

{
  "status": "ValidCommercial",
  "reason": null,
  "licenseType": "Team",
  "isEvaluation": false,
  "productionAllowed": true,
  "validFrom": "2026-10-01T00:00:00+00:00",
  "expiresAt": "2027-09-30T23:59:59+00:00",
  "daysRemaining": 187,
  "checkedAt": "2027-03-27T09:14:02+00:00"
}

status is one of ValidCommercial, ValidEvaluation, Missing, Invalid and Expired. The endpoint reports the license's state only: it never shows whom the license was issued to, the license number or the licensed instance count. For a missing or invalid license every field after reason, except checkedAt, is empty.

Monitoring

Each Runtime instance reports its own license, so an instance started without the license folder mounted shows up on its own.

• Metrics: apimapper_runtime_license_state{status="…"} (1 for the current status) and apimapper_runtime_license_days_remaining. A useful alert is a status of Missing, Invalid or Expired, or fewer than 30 days remaining.
• Audit trail: license.status.degraded is recorded at startup and every hour while the license is missing, invalid or expired, and license.status.changed whenever the state changes. Both are platform-level entries in the licensing category and reach your configured audit targets.