Skip to content

Licensing url change warning #805

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
JamesW1 merged 2 commits into from
Aug 12, 2026
+12 −3
Merged

Licensing url change warning #805

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
223c2fb
Document license re-activation when moving an instance to a new URL
JamesW1 Aug 11, 2026
77698bb
add license clarifications
JamesW1 Aug 11, 2026
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
15 changes: 12 additions & 3 deletions content/licensing/1.overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,13 +66,14 @@ If `PUBLIC_URL` is not set, Directus will still start successfully with a warnin

Attempts to add a license key during setup will grant access to the Studio, but license activation will fail and an error will be logged. Likewise, adding or managing a license through **Settings → License** will fail and display the following error:


```
[INVALID_PAYLOAD] Invalid payload. public_url must be a valid absolute URL.
```

If you encounter this error, configure `PUBLIC_URL` with a qualified URL, restart Directus, and then re-apply the license.

If you change `PUBLIC_URL` after activation, you must re-apply your license so it binds to the new URL. See [Moving an Instance to a New URL](#moving-an-instance-to-a-new-url) for the steps and the consequences of skipping them.

::callout{icon="i-lucide-info" color="info"}
In addition to licensing, `PUBLIC_URL` is used throughout Directus for features such as OAuth redirects, password reset emails, and other public-facing links. For more information, see the [`PUBLIC_URL` entry in the general configuration reference](/configuration/general).
::
Expand Down Expand Up @@ -188,9 +189,17 @@ If your current usage is above core tier limits when you deactivate, the Studio

### Moving an Instance to a New URL

If you change the `PUBLIC_URL` of an existing instance — for example, when migrating to a new domain — the license key will register a new activation against the new URL. The previous activation against the old URL remains in place until you deactivate it.
A license activation is bound to the `PUBLIC_URL` value at the time it is created. Changing the `PUBLIC_URL` of an existing instance, such as when migrating to a new domain, does not update the binding automatically.

To move an instance to a new URL:

To reuse the same license on the new URL without exceeding your license's activation limit, deactivate the license on the old instance **before** bringing the new one online.
1. Deactivate the license while `PUBLIC_URL` still holds its old value. This frees the old activation so it does not count against your activation limit. See [Deactivating a License](#deactivating-a-license).
2. Update `PUBLIC_URL` and restart Directus.
3. Re-apply your license key. This registers a new activation against the new URL.

::callout{icon="i-lucide-triangle-alert" color="warning"}
**Changing `PUBLIC_URL` without re-applying your license eventually downgrades the instance to the core tier.** Once the URL no longer matches its activation, periodic revalidation fails and the instance continues to run on its cached license. When the cached license expires, the downgrade takes effect without warning. If usage is above core tier limits at that point, the instance becomes [locked down](#locked-down-instances) and the API returns errors until the license is resolved. Your data is unaffected, and re-applying the license key restores normal operation immediately.
::

### Replicas and Horizontal Scaling

Expand Down
Loading