Licensing
Overview
Without a license key, the instance runs on the Starter plan by default. For every commercial Monospace instance, it runs using a license. The license carries license entitlements: the limits and features the instance may use, such as the number of workspaces or whether single sign-on is available.
License entitlements are separate from the permission entitlements that policies grant to members. See the Permissions Reference for those.
Apply a License
The instance takes its license from one of two environment variables, or runs on Starter when neither is set.
| Configuration | License | Licensing service |
|---|---|---|
MONOSPACE_LICENSE__KEY | Online license, activated and revalidated over HTTPS | Required at every startup and for revalidation |
MONOSPACE_LICENSE__TOKEN | Offline license, verified locally | Never contacted |
Setting both variables fails startup:
Invalid configuration. Use either MONOSPACE_LICENSE__KEY or MONOSPACE_LICENSE__TOKEN but not both at the same time.
In clustered mode, set the same license variable on every replica. Replicas share one activation through the system database.
License Key Activation
On the first start with a key, Monospace activates it with the licensing service at https://licensing.monospace.io. Activation sends the key, the environment ID Monospace generated when the system database was installed, and the public URL from MONOSPACE_BASE_URL
Every later start revalidates the stored license with the service. Monospace also revalidates on the schedule the license specifies, never more than once an hour, and whenever an organization administrator selects Refresh License in the Studio or calls POST /api/system/license/refresh. Revalidation applies changes to the license, such as added workspaces or a new expiry date, without a restart.
The licensing service must be reachable at every startup, unless using the offline license token. If it is not reachable, the instance does not start. If the service is unreachable during a scheduled revalidation, the instance keeps its current entitlements, logs a warning, and the Studio License panel reports the service as unreachable. See License Status for what happens when the license reaches its expiry date in that state.
To move to a different license, replace the key and restart; Monospace activates the new key. To return to Starter, unset the variable and restart.
Startup Failures
A license problem stops the instance before it serves requests. The log names the cause.
| Log message | Cause |
|---|---|
Invalid configuration. Use either MONOSPACE_LICENSE__KEY or MONOSPACE_LICENSE__TOKEN but not both at the same time. | Both variables are set |
Invalid key, caused by License key not for Monospace | The key does not begin with M |
Invalid key, caused by Invalid license key checksum | The key is mistyped |
Could not reach the license server. | A key is configured and the licensing service is unreachable |
Failed to request from license server. | The licensing service rejected the request; the cause follows, for example LicenseExpired for a key that expired before its first activation, or License usage limit reached for a key already activated on its maximum number of instances |
This license does not include offline use. | The token's license does not include offline use |
Invalid token | The token is malformed, its signature does not verify, or it was issued for another product |
A license that expires after activation does not stop startup. The instance starts with the license locked; see License Status.
Startup Usage Check
After applying the license, Monospace compares existing usage with every hard limit. If usage exceeds a limit, the instance does not start and the log lists each violation:
License entitlement check failed; startup has been rejected:
- workspaces: usage 2 exceeds hard limit 1
- sso_enabled: usage true is not allowed
note: disabled SSO provider found
- seats: usage 4 exceeds hard limit 3 (workspace: blog)
note: workspace invitations are included in seat usage
The check runs on every start, so it also applies after you remove a key or a license is reissued with lower limits. To start the instance, reduce usage to within the limits, set a key for a license that covers the usage, or ask support for a temporary extension so you can reduce usage while the instance runs.
License Status
A license has one of three statuses. GET /api/system/info reports it, and the Studio acts on it.
| Status | Meaning | Effect |
|---|---|---|
active | The license is within its term | None |
grace | The expiry date has passed, and the grace period the license grants has not ended | None. Organization and workspace administrators see a warning in the Studio |
locked | The grace period has ended, or the licensing service reported the license as expired, suspended, or canceled | Every request to /api/{workspace}/items/... returns 402 with System is locked. Please contact system administrator. The Studio shows a lock screen to signed-in members |
The Starter license never expires.
When a license reaches its expiry date, the status becomes grace for the grace period the license specifies, then locked. A revalidation that reaches the licensing service ends this early: a renewed license returns to active, and a license the service reports as expired, suspended, or canceled locks at once. Administrators see a warning in the Studio from 14 days before expiry and throughout the grace period.
Endpoints outside /items, including sign-in, the system endpoints, and the license endpoints, keep working while the license is locked, so an administrator can resolve it. To unlock an instance:
- Renew or extend the license, then revalidate with Refresh License in the Studio or
POST /api/system/license/refresh. Scheduled revalidation continues while locked, so the instance also unlocks on its own once the licensing service returns a valid license. No restart is needed. For an offline license, set the new token and restart. - Return to Starter by unsetting the license variables and restarting. The startup usage check applies, so reduce usage to within the Starter limits first.
Usage Measurement
Monospace measures usage the same way at startup, before a write, and in the license endpoints.
| Entitlement | Scope | Counted |
|---|---|---|
workspaces | Organization | Every workspace |
seats | Per workspace | Active members plus unexpired workspace invitations. Suspended members, service accounts, and organization-only invitations are not counted |
custom_roles | Per workspace | Every role except the built-in Administrator and Public roles |
custom_policies | Per workspace | Every policy you created, whether or not it is attached to a role |
custom_permission_rules_enabled | Per workspace | Whether any policy you created uses an item filter, a specific-field selection, or a validation rule |
service_accounts | Organization | Every service account |
sso_enabled | Organization | Whether any sign-in provider other than password exists, including a disabled one |
A per-workspace limit applies to each workspace separately. Suspending a member frees their seat; deleting a sign-in provider, not disabling it, ends SSO usage.
View License and Usage
Organization administrators open Organization Settings > License. The panel shows the license name, its expiry date, and each entitlement with current usage against its limit; expand a per-workspace entitlement to see each workspace. It flags usage above a soft limit and a licensing service that could not be reached. Refresh License is available for a license applied with a key.
See Also
- Configuration -- the license environment variables
- System Requirements -- outbound access to the licensing service
- System Endpoints -- the license and instance info endpoints
- Errors -- the error response shape
- Permissions Reference -- permission entitlements, which are separate from license entitlements