Skip to main content
ALTCHA®

Configure the license

Sentinel needs an active license to serve its API. You set the license in the configuration file, either as an offline file or as an online key. For plans and limits, see Plans & Licensing.

The license is set only in sentinel.toml. The admin UI and the API show the license status but can't install, activate, or release a license.

Get a license

Register at cloud.altcha.org and create a Sentinel V2 license, or a trial license, in the Licenses section. The cloud app issues the license in either form:

FormConfig keyWhat the cloud app needsUse it when
Online license key (SENT-…)[license] keyNothing; Sentinel binds the key to the deployment when it activates it.Sentinel can reach the license server. Activation and renewal are automatic.
License file (signed JSON)[license] fileThe deployment ID of your Sentinel; see Option B.Sentinel has no internet access, or you want no outbound license traffic.

Set at most one of them. Setting both stops startup with [license] file and key are mutually exclusive.

Option A — Online license key

Store the key as a secret and reference it:

[license]
key = "${file:/run/secrets/sentinel_license_key}"

Restart Sentinel. On startup, one replica exchanges the key for a license bound to this deployment and stores it in the database, so every replica shares it. The key itself is never stored.

Sentinel then refreshes the license in the background, about once a day. Only one replica refreshes at a time. A failed refresh keeps the cached license, retries with a backoff from 60 seconds to 1 hour, and records the cause (DNS, connection, TLS, or timeout) in refresh.last_error of the license status. Requests to the license server time out after 15 seconds.

If the license isn't refreshed before its refresh deadline, its status becomes refresh_overdue and the functional API stops (see Status values). Removing the key also stops the refresh.

[license] server defaults to https://license.altcha.org. You can point it at another URL, for example a forwarding proxy, but you can't turn it off; an empty value means the default. Sentinel contacts it only when a key is set. Outbound requests honor HTTPS_PROXY; see Outbound proxy & air-gapped deployments.

Option B — Offline license file

A license file is verified offline with the signature embedded in it. It's the only option for air-gapped deployments.

  1. Copy the deployment ID. A license file is bound to one deployment, so the cloud app asks for its ID. Start Sentinel without a license, sign in as root, open License, and click Copy deployment ID next to Deployment ID.

    Without the admin UI, print the deployment's license request inside the running container, so it uses the server's configuration and database:

    docker exec sentinel /usr/local/bin/altcha-sentinel license request > sentinel-license-request.json

    The file holds the deployment ID:

    {
      "app_version": "2.0.0-beta.1",
      "created_at": 1794819530,
      "deployment_id": "dep_…",
      "product": "sentinel"
    }

    The command creates the deployment ID in the database when needed. A root user can also download the same JSON from GET /v2/license/request:

    curl -H 'Authorization: Bearer <jwt>' -o sentinel-license-request.json \
      https://sentinel.example.com/v2/license/request

    The deployment ID is stored in the database, so every replica sharing that database has the same ID. A new database gets a new ID, and a file issued for the old one no longer applies.

  2. Create the license file in the cloud app's Licenses section with that deployment ID, and download it.

  3. Check the file before you install it. Mount it into a one-off container:

    docker run --rm -v "$PWD/license.json:/tmp/license.json:ro" \
      ghcr.io/altcha-org/sentinel:2.0.0-beta.1 license inspect /tmp/license.json

    It prints the signer, the digest, the decoded license, and the signature result. It needs no configuration or database:

    signer root: root-a
    signer kid: file-2026-11
    digest: 1d11…50d2
    {
      "constraints": { "deployment": "dep_…" },
      "features": ["audit_logs", "clickhouse", "exotdb.backend.postgres", "exotdb.backend.sqlite", "ldap", "oauth", …],
      "id": "lic_…",
      "issued_at": 1794799666,
      "licensee": { "id": "acc_…", "name": "Example Inc." },
      "limits": { "accounts": 10, "api_keys": 10, "instances": 3, "security_groups": 10, "users": 10 },
      "not_after": 1797391642,
      "not_before": 1794796066,
      "plan": "trial",
      "product": "sentinel",
      "v": 1
    }
    signature: valid; bound to deployment dep_…

    An invalid file prints signature: INVALID: <reason> and exits with 1.

  4. Point the config at the file and restart:

    [license]
    file = "/run/secrets/sentinel_license.json"

At startup, Sentinel imports the file when it was issued later than the stored license; an older file is ignored with a warning. A license whose start date is in the future is kept as pending and applied when it becomes valid. A file that can't be read, has an invalid signature, or is bound to another deployment stops startup, for example:

Error: invalid licence file /run/secrets/sentinel_license.json: licence is bound to another deployment

Check the license status

The startup log states the result:

INFO exotdb_license_runtime: licensed to "Example Inc." (trial, lic_…), valid until 2026-12-16, instances 1/3
INFO exotdb_license_runtime: no licence installed; running on the baseline (exotdb.backend.sqlite, 3 instances)

Root users see the status on the License page of the admin UI, or through the API with a session token:

curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/license
{
  "data": {
    "phase": "ready",
    "status": "active",
    "source": "licensed",
    "deployment_id": "dep_…",
    "pinned": "file",
    "license": { "id": "lic_…", "plan": "trial", "licensee": { "name": "Example Inc." }, "environment": "production", "not_after": 1797391642, "bound": true, … },
    "pending": null,
    "entitlements": { "features": ["audit_logs", "exotdb.backend.postgres", "exotdb.backend.sqlite", …], "limits": { "accounts": 10, "instances": 3, "users": 10, … } },
    "instances": { "limit": 3, "used": 1, "state": "regular", "slots": [ … ] },
    "refresh": { "online": false, "last_success": null, "last_error": null, "failing_since": null, "next_at": null }
  }
}

source is licensed while the license's features and limits apply, otherwise baseline. pinned names the config key that set the license (file or key). GET /v2/license and GET /v2/license/request need a root user (403 ROOT_PRIVILEGES_REQUIRED otherwise). Any signed-in user can read a short summary at GET /v2/me/license. Schemas are in the API reference.

Status values

statusMeaningFunctional APIFeatures and limits
activeThe license applies.ServedLicensed
expiredPast its end date.403 LICENSE_NOT_ACTIVELicensed
refresh_overdueAn online license wasn't refreshed in time.403 LICENSE_NOT_ACTIVELicensed
revokedRevoked by ALTCHA.403 LICENSE_NOT_ACTIVEBaseline
not_yet_validBefore its start date.403 LICENSE_NOT_ACTIVEBaseline
noneNo license installed.403 LICENSE_NOT_ACTIVEBaseline

An expired or refresh_overdue license keeps its features and limits, including the database backend and instance count, so LDAP and OAuth users can still sign in and no replica is pushed out. Only the functional API stops. Any grace period is already part of the license's end date.

What a missing license blocks

The functional API is served only with an active license. Without one, the widget routes (/v2/challenge, /v2/challenge/audio/{file}, /v2/verify, /v2/inspect) and the feature routes (/v2/classifier, /v2/similarity, /v2/eml, and the other detection endpoints) answer:

curl -i 'https://sentinel.example.com/v2/challenge?apiKey=key_…'
HTTP/1.1 403 Forbidden
content-type: application/json

{"code":"LICENSE_NOT_ACTIVE","data":{"status":"none"},"error":"No licence is installed; this endpoint needs an active licence.","statusCode":403}

data.status holds one of the status values. Sign-in, management routes, /v2/license*, and /v2/doctor* keep working, so you can sign in and diagnose the instance.

The baseline applies without a usable license (none, not_yet_valid, revoked): embedded SQLite only, 3 instances, and 1 account, 1 user, 1 API key, and 1 security group, with no licensed features. With an unlicensed database backend, most /v2 routes answer 403 BACKEND_NOT_LICENSED. Nothing is deleted when a license lapses: existing accounts, users, keys, groups, and logs stay usable, and only new ones are limited (403 LICENSE_LIMIT_REACHED). Which plan includes which feature and limit is listed in Plans & Licensing; every license error is in Error codes.

Instance slots

Each running replica holds a leased instance slot in the shared database, up to the license's instances limit, plus a few short-lived burst slots for rolling deploys. A replica that can't get a slot within 60 seconds at startup exits; one that loses its slot later answers 503 LICENSE_INSTANCE_LIMIT. A replica with [license] standby = true instead waits without a slot as a warm failover and takes over when a slot frees up. The node ID comes from the HOSTNAME environment variable, so give each process a unique, stable HOSTNAME. Leases, burst rules, standby instances, and restart behavior are covered in Clustering & high availability.

Non-production licenses

Each license has a production key and a non-production key in cloud.altcha.org; each key allows its own number of deployments (see Deployments). Under a license issued for the non-production key, every /v2 response carries this header:

X-Sentinel-License: non-production

The license status shows "environment": "non-production", and doctor reports it. Use such licenses for staging and test environments.

Alerts and metrics

Sentinel raises these system-wide alerts, visible to root users:

RuleSeverityRaised when
license_expiredhighThe license expired, was revoked, or is overdue for refresh; the functional API is refused.
license_instance_limithighThis replica is over the licensed instance limit.
license_refresh_failingmediumOnline license refresh has been failing for 24 hours.
license_clock_rollbackmediumThe system clock was set back.

With [prometheus] enabled, these metrics are exported (see Monitoring):

MetricMeaning
altcha_sentinel_license_info{license_id,plan,status,environment}Always 1; status="none" without a license.
altcha_sentinel_license_expiry_timestamp_secondsThe license end date (not_after).
altcha_sentinel_license_refresh_before_timestamp_secondsThe online refresh deadline; online licenses only.
altcha_sentinel_license_issued_at_timestamp_secondsWhen the license was issued.
altcha_sentinel_license_instances_limitThe licensed instance limit.
altcha_sentinel_license_instances_usedInstance slots in use.

Alert on altcha_sentinel_license_expiry_timestamp_seconds - time() to renew in time.

Start typing to search...

↑ ↓ Navigate ↵ Select