Reference

Licensing

How Monospace applies a license, checks usage against it, and behaves when a license expires or locks.

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:

logs

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. The service returns a signed license, which Monospace stores in the system database. Set MONOSPACE_BASE_URL before activating, because the licensing service records it against the activation.

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:

logs

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.

Limit Errors

While the instance runs, Monospace checks an operation that adds usage against the license before applying it. An operation that would exceed a hard limit returns 402 with the message The requested operation would exceed licensed hard limits. The code identifies the entitlement, and meta.violations reports the usage the operation would produce against the limit:

response.json

{
  "message": "The requested operation would exceed licensed hard limits",
  "code": "6004",
  "meta": {
    "violations": [
      { "entitlement": "seats", "usage": 4, "hard_limit": 3 }
    ]
  }
}

For an entitlement that is on or off, the violation carries "usage": true and "allowed": false in place of usage and hard_limit.

Code	Entitlement	Returned when
`6001`	`workspaces`	Creating a workspace
`6002`	`service_accounts`	Creating a service account
`6003`	`sso_enabled`	Creating a sign-in provider other than password
`6004`	`seats`	Inviting members to a workspace, renewing an expired workspace invitation, or reactivating a suspended member
`6005`	`custom_roles`	Creating a role
`6006`	`custom_permission_rules_enabled`	Creating or updating a policy so it uses an item filter, a specific-field selection, or a validation rule
`6007`	`custom_policies`	Creating a policy
`6008`	`audit_logs_enabled`	Reading audit logs with `GET /api/system/audit-logs` when the license does not include them

A numeric limit rejects only an operation that increases usage beyond the limit. When usage already exceeds a limit, operations that keep or reduce it succeed, so you can clean up. An on-or-off entitlement rejects only an operation that newly turns it on.

Code 6008 returns the message Audit logs are not included in your license. and carries no meta.

A locked license returns 402 with System is locked. Please contact system administrator. and no code; see License Status. See Errors for the error response shape.

View License and Usage

Organization administrators open Settings > Organization > 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.