# Configure the license

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/plans/).

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](https://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:

| Form | Config key | What the cloud app needs | Use it when |
| --- | --- | --- | --- |
| Online license key (`SENT-…`) | `[license] key` | Nothing; 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] file` | The deployment ID of your Sentinel; see [Option B](#option-b--offline-license-file). | 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:

```toml
[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](#check-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](#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](/docs/sentinel/v2/configure/air-gapped/).

## 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:

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

The file holds the deployment ID:

```json
{
 "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`:

```bash
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:

```bash
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:

```text
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:

```toml
[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:

```text
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:

```text
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:

```bash
curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/license
```

```json
{
"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](/sentinel-api-docs-v2.html#tag/license/GET/v2/license).

### Status values

| `status` | Meaning | Functional API | Features and limits |
| --- | --- | --- | --- |
| `active` | The license applies. | Served | Licensed |
| `expired` | Past its end date. | `403 LICENSE_NOT_ACTIVE` | Licensed |
| `refresh_overdue` | An online license wasn't refreshed in time. | `403 LICENSE_NOT_ACTIVE` | Licensed |
| `revoked` | Revoked by ALTCHA. | `403 LICENSE_NOT_ACTIVE` | Baseline |
| `not_yet_valid` | Before its start date. | `403 LICENSE_NOT_ACTIVE` | Baseline |
| `none` | No license installed. | `403 LICENSE_NOT_ACTIVE` | Baseline |

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:

```bash
curl -i 'https://sentinel.example.com/v2/challenge?apiKey=key_…'
```

```http
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](#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](/docs/sentinel/v2/plans/); every license error is in [Error codes](/docs/sentinel/v2/reference/errors/).

## 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](/docs/sentinel/v2/operations/clustering/).

## 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](/docs/sentinel/v2/plans/#deployments)). Under a license issued for the non-production key, every `/v2` response carries this header:

```http
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](/docs/sentinel/v2/operations/alerts/), visible to root users:

| Rule | Severity | Raised when |
| --- | --- | --- |
| `license_expired` | high | The license expired, was revoked, or is overdue for refresh; the functional API is refused. |
| `license_instance_limit` | high | This replica is over the licensed instance limit. |
| `license_refresh_failing` | medium | Online license refresh has been failing for 24 hours. |
| `license_clock_rollback` | medium | The system clock was set back. |

With `[prometheus]` enabled, these metrics are exported (see [Monitoring](/docs/sentinel/v2/operations/monitoring/)):

| Metric | Meaning |
| --- | --- |
| `altcha_sentinel_license_info{license_id,plan,status,environment}` | Always `1`; `status="none"` without a license. |
| `altcha_sentinel_license_expiry_timestamp_seconds` | The license end date (`not_after`). |
| `altcha_sentinel_license_refresh_before_timestamp_seconds` | The online refresh deadline; online licenses only. |
| `altcha_sentinel_license_issued_at_timestamp_seconds` | When the license was issued. |
| `altcha_sentinel_license_instances_limit` | The licensed instance limit. |
| `altcha_sentinel_license_instances_used` | Instance slots in use. |

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

## Related

- [`[license]` in the Configuration reference](/docs/sentinel/v2/reference/configuration/#license)
- [`license inspect` and `license request` in the CLI reference](/docs/sentinel/v2/reference/cli/)
- [Plans & Licensing](/docs/sentinel/v2/plans/)
- [Outbound proxy & air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/)
