Activate and manage your license
This guide shows you how to activate, refresh, and deactivate an Erde license. Erde requires a valid license to serve any data; you activate one during first-run setup or from the command line, refresh it when you renew, and deactivate it when you retire the server.
A license is a single signed file named license.bin, stored next to the server executable (for example C:\Program Files\Erde\api\license.bin). It is bound to the machine it was activated on, so it cannot be copied to an unrelated server.
- Role required: Administrator for the in-app actions (Refresh, Deactivate). The command-line tools run on the server host with file-system access to the install directory.
- Prerequisites: A license key from Erde, and outbound internet access to the license issuer at
https://license.erde.dev. Licensing is Windows-only.
What a license governs
Erde validates the license locally at startup — there is no network call to start the server. If license.bin is missing, corrupt, has an invalid signature, or is bound to a different machine, the server still starts but blocks data API access until you activate a valid license; sign-in, password reset, the license-status check, and the admin license endpoints stay reachable so an administrator can recover from the UI.
The license carries the customer name, edition, the activation date, and the Software Maintenance Agreement (SMA) expiry date. An expired SMA does not block access — it only changes the status indicator in the admin dashboard. Only a missing or invalid license.bin blocks access.
Figure: the license lifecycle. Refresh updates claims in place; Deactivate releases the activation slot and removes license.bin.
Activate a license
Activate during first-run setup, or — for an existing install — from the command line.
During setup
The first-run wizard includes a License Activation step:
- Enter your key in the License Key field (format
XXXX-XXXX-XXXX-XXXX). - Select Activate. On success a banner shows License Activated with the Customer, Edition, and SMA Expires date.
- To proceed without a license, select Skip for now. The server starts but blocks all access until you activate later — sign in and use the activation form on the License Required overlay, or run
--activatefrom the command line.
For the full setup walkthrough, see Complete first-run setup.
From the license overlay (after setup)
If the server is running unlicensed (activation was skipped, or license.bin was lost), the full-screen License Required overlay includes an activation form:
- Sign in as an Administrator (sign-in stays reachable on an unlicensed server).
- Enter your key in the overlay's License Key field and select Activate.
- On success the overlay confirms the customer name and the server restarts itself to complete initialization — database migration and background services are skipped on an unlicensed boot, so activation finishes with a restart. The page reloads automatically once the server is back.
From the command line
To activate (or reactivate) an already-installed server, run Erde.Server.exe from the install directory with --activate:
& "C:\Program Files\Erde\api\Erde.Server.exe" --activate --key YOUR-KEY --server https://license.erde.dev
| Argument | Required | Notes |
|---|---|---|
--key | Yes | Your license key. The command exits with an error if omitted. |
--server | No | License-issuer URL; defaults to https://license.erde.dev. |
The command contacts the issuer, validates the issued token on this machine, writes license.bin, and prints the customer, edition, SMA expiry, and the file path. It does not start the web host.
Unlike the in-app overlay form, the command runs out of process, so restart the Erde service afterward for the license to take effect.
Refresh a license
Refresh when you renew your SMA or change edition on the same machine. The current key is read from license.bin, and the issuer re-issues a token with updated claims.
From the admin dashboard
- Go to Administration → Dashboard (route
/admin). The admin area opens from the Admin item in the top navigation. - On the License card, select Refresh License.
- In the confirmation dialog, select Refresh License again.
The new license takes effect immediately — no restart required. A toast confirms the refresh and shows the new SMA expiry date, for example License refreshed. SMA expires 2027-01-15. This works even when the current license has an expired SMA, because the refresh endpoint stays reachable to an authenticated administrator.
From the command line
& "C:\Program Files\Erde\api\Erde.Server.exe" --refresh-license --server https://license.erde.dev
The --server argument is optional and defaults to https://license.erde.dev; no --key is needed because the key is read from the existing license.bin. Unlike the admin UI, the command runs out of process, so it prints Restart Erde for the updated license to take effect.
Refresh is always manual — there is no scheduled or background refresh. Run it from the dashboard or the command line whenever your license changes.
Deactivate a license
Deactivate when you decommission a server or move Erde to new hardware. This releases the activation slot on the issuer so another machine can use it, then deletes the local license.bin.
Deactivation is destructive. It releases this installation's activation slot and disables Erde on this server. The server stops serving API requests immediately, the admin UI becomes unavailable, and license.bin is deleted. To bring the server (or its replacement) back online, activate again — from the License Required overlay's activation form or with --activate — which consumes an activation slot. Shut the server down after deactivating if you are decommissioning it.
From the admin dashboard
- Go to Administration → Dashboard (route
/admin). - On the License card, select Deactivate (the red button).
- Read the consequences in the dialog, then select Deactivate This Installation.
Once the slot is released, a full-screen message confirms how many activation slots are now available and that license.bin has been removed. If the file could not be deleted automatically, the message instead tells you to delete it manually before restart.
From the command line
& "C:\Program Files\Erde\api\Erde.Server.exe" --deactivate-license --server https://license.erde.dev
The key is read from license.bin; --server is optional. On success the command prints the customer and Slots remaining: X / Y, then This installation is no longer licensed.
If this machine is already offline or unrecoverable, do not run deactivation there — contact Erde support to release the slot manually.
Where license status appears
The License card on the admin dashboard (Administration → Dashboard, route /admin) shows four rows:
| Row | Value |
|---|---|
| Customer | The customer name on the license |
| Edition | The licensed edition |
| Activated | The activation date (ISO format) |
| SMA Expires | The SMA expiry date, with a status indicator |
The status dot beside SMA Expires is green while the SMA is current and turns amber once it has expired. An expired SMA only changes this indicator — it does not lock the product.
What the license-block overlay does
When the server has no valid license, every administrator and user sees a full-screen License Required overlay covering the entire app. It shows the server's error message (for example, that the license is registered to a different machine), an activation form where a signed-in administrator can enter a license key, and help text pointing at the command-line alternative.
Behind the scenes, the server returns HTTP 451 for blocked API calls, and the client latches into the unlicensed state on the first such response. Sign-in, password reset (forgot/reset password), and the admin license endpoints stay reachable — so an administrator can still log in (or recover a forgotten password) and activate or refresh a license without server console access.
Troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| License Required overlay on every page | license.bin is missing, corrupt, or bound to another machine | Sign in and activate from the overlay's form, or run --activate on the server and restart |
ERROR: --key is required. | You ran --activate without --key | Re-run with --key YOUR-KEY |
No license file found ... Run --activate first. | --refresh-license ran with no license.bin present | Activate first with --activate |
| Refresh rejected (machine moved or revoked) | The issuer declined to re-issue on this machine | Reinstall and reactivate with your key; contact support if the slot is stuck |
| The SMA Expires dot turns amber | The SMA period has ended | Renew with Erde, then Refresh License; access is not blocked in the meantime |
Deactivation left license.bin behind | The slot released but the local file could not be deleted | Delete license.bin manually before restarting the server |