Skip to content

Move offline token callout #814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChristopherJennings merged 1 commit into from
Aug 24, 2026
+26 −27
Merged

Move offline token callout #814

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 26 additions & 27 deletions content/licensing/1.overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,14 +83,10 @@ In addition to licensing, `PUBLIC_URL` is used throughout Directus for features
There are two ways to configure a license:

- **License key** — a string in the format `DXXXX-XXXXX-XXXXX-XXXXX-XXXXC`. On first use, it binds your license to a specific project and `PUBLIC_URL`. License keys can be set via environment variable or added through the Studio.
- **License token** — a pre-issued token containing your entitlements, validated locally without contacting the licensing service. Tokens are only set via environment variable and are intended for **offline use**, in environments without outbound network access. Any change to the license requires a new token to be issued and deployed.
- **License token** — a pre-issued token containing your entitlements, validated locally without contacting the licensing service. Tokens are only set via environment variable and are intended for [**offline use**](/licensing/overview#offline-mode), in environments without outbound network access. Any change to the license requires a new token to be issued and deployed.

You configure one or the other — not both. Setting both in your environment is a configuration error and Directus will refuse to start.

::callout{icon="i-lucide-triangle-alert" color="warning"}
**Offline license tokens are only available on Enterprise plans.** Most self-hosted instances should use a license key. The core tier has no license to validate and can be run air-gapped without a token — only paid plans that need to run without outbound network access require one.
::

## License Modes

### Online Mode
Expand All @@ -107,15 +103,19 @@ Because offline instances cannot be reached, suspension or cancellation only tak

Offline mode is only available on Enterprise plans. If you are running the core tier, you do not need a token — Directus has no license to validate.

::callout{icon="i-lucide-triangle-alert" color="warning"}
**Offline license tokens are only available on Enterprise plans.** Most self-hosted instances should use a license key. The core tier has no license to validate and can be run air-gapped without a token — only paid plans that need to run without outbound network access require one.
::

## Configuration

Licenses are configured through one of three sources, applied in the following order of precedence:

| Source | Precedence | UI editable |
| --- | --- | --- |
| `LICENSE_KEY` (environment) | 1 | No |
| `LICENSE_TOKEN` (environment) | 2 | No |
| License key in database (set via Studio) | 3 | Yes |
| Source | Precedence | UI editable |
| ---------------------------------------- | ---------- | ----------- |
| `LICENSE_KEY` (environment) | 1 | No |
| `LICENSE_TOKEN` (environment) | 2 | No |
| License key in database (set via Studio) | 3 | Yes |

When a key or token is set in the environment, any license key management actions are disabled. To change the license, update the environment variable and restart Directus.

Expand All @@ -127,30 +127,29 @@ See the [General configuration](/configuration/general#license) reference for th

In online mode, Directus makes outbound HTTPS requests to `https://licensing.directus.com`. If your network restricts outbound traffic, we recommend allowing the following endpoints:

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/.well-known/jwks.json` | Token signature verification |
| `POST` | `/api/licenses/preview` | License preview before activation |
| `POST` | `/api/licenses/activate` | Initial license activation |
| `POST` | `/api/licenses/refresh` | Periodic license revalidation |
| `POST` | `/api/licenses/update` | Plan or addon changes |
| `POST` | `/api/licenses/deactivate` | License deactivation |
| `POST` | `/api/licenses/portal` | Opening the Stripe billing portal |
| `GET` | `/api/licenses/addons/options` | Fetching available addon options |
| `PATCH` | `/api/licenses/addons` | Purchasing or modifying addons |
| `DELETE` | `/api/licenses/addons` | Removing addons |
| Method | Endpoint | Purpose |
| -------- | ------------------------------ | --------------------------------- |
| `GET` | `/.well-known/jwks.json` | Token signature verification |
| `POST` | `/api/licenses/preview` | License preview before activation |
| `POST` | `/api/licenses/activate` | Initial license activation |
| `POST` | `/api/licenses/refresh` | Periodic license revalidation |
| `POST` | `/api/licenses/update` | Plan or addon changes |
| `POST` | `/api/licenses/deactivate` | License deactivation |
| `POST` | `/api/licenses/portal` | Opening the Stripe billing portal |
| `GET` | `/api/licenses/addons/options` | Fetching available addon options |
| `PATCH` | `/api/licenses/addons` | Purchasing or modifying addons |
| `DELETE` | `/api/licenses/addons` | Removing addons |

**Notice**: These endpoints are subject to future change and the list may be modified or be extended in the future.

If outbound access to `https://licensing.directus.com` is not possible, use an [offline license token](#offline-mode) instead. Offline tokens are validated locally and require no outbound network access. Offline mode is only available on Enterprise plans.


## License Statuses

| Status | Meaning |
| --- | --- |
| **Active** | License is valid and the instance is within its entitlement limits. |
| **Grace** | License has passed its expiry or the instance has exceeded its limits, but the configured grace period has not yet elapsed. The instance continues to operate normally. |
| Status | Meaning |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Active** | License is valid and the instance is within its entitlement limits. |
| **Grace** | License has passed its expiry or the instance has exceeded its limits, but the configured grace period has not yet elapsed. The instance continues to operate normally. |
| **Locked** | The instance has exceeded its entitlement limits and is outside any applicable grace period. Main parts of the instance are locked down and resolution is required before normal operation can resume. |

::callout{icon="i-lucide-info"}
Expand Down
Loading