Licensing
A self-hosted Plenary instance is free to run. Without a license it is on the Free plan: one site, no forms, no single sign-on, and no GraphQL API. Everything else works, with as many users as you like. A license lifts all four limits. It is a signed, single-line token that the server checks entirely offline: there is no activation server and nothing is reported anywhere. Plenary Cloud instances are licensed by their subscription and need no token.
The Free plan
Section titled “The Free plan”| Free plan | Licensed | |
|---|---|---|
| Sites | 1 | Unlimited |
| Forms | Not included | Included |
| Single sign-on | Not included | Included |
| GraphQL API | Not included | Included |
- Sites: creating a second site is refused with
403 license_limit_sites. This includes a metadata import that would create one. - Forms: creating or changing a form definition, and submitting a form from a site, are refused with
403 license_feature_forms. Existing forms and their entries stay readable and exportable; you can still mark, delete, and export entries, and delete forms. - Single sign-on: signing in through an external identity provider, and saving or testing the connection, are refused with
403 license_feature_sso. The sign-in page shows no single sign-on button, and the stored connection is kept. See Single sign-on. - GraphQL API: every GraphQL request, including the schema endpoint, is refused with
403 license_feature_graphql. The same content stays readable over the Content API. See GraphQL API.
Nothing else is limited: users, content models, entries, media, the page builder, webhooks, transformers, API keys, roles, and scheduled publishing all work on the Free plan.
Over the limits
Section titled “Over the limits”An instance can be over the Free plan limits without having broken a rule: an evaluation license expired, or the instance was upgraded past its license’s update window. Everything it has keeps working. It cannot add sites, forms stop accepting submissions, GraphQL queries are refused, and the console shows a banner naming the exceeded limits until a license is installed.
What a license grants
Section titled “What a license grants”A license grants the whole product. There are no editions, seat counts, site limits, or feature flags.
| License kind | Expires | Use |
|---|---|---|
Full (full) |
Never | Production. Valid forever on every release it covers. |
Evaluation (evaluation) |
On a fixed date | Trials. Usually 30 days. Identical to a full license until it expires. |
Every license also names:
- Permitted hosts: the hostnames the license works on, such as
cms.example.comor a wildcard such as*.staging.example.com. A wildcard matches exactly one label in the leftmost position:*.staging.example.commatchespr-12.staging.example.combut nota.b.staging.example.com. - Update window (optional): the latest release date the license covers. Every Plenary release published on or before that date is licensed forever. A release published after it needs a renewed license. A license without an update window covers every release.
The token looks like plv1. followed by two base64url segments. It is not a secret: it reveals only the customer name, hosts, and dates. Treat it like any other configuration value.
How the host is checked
Section titled “How the host is checked”Plenary compares the license’s permitted hosts with the hostname of server.public_url in plenary.yaml (lowercased, port removed). It never uses the request’s Host header.
When that hostname is localhost or 127.0.0.1, license enforcement is off. Local development needs no license, and the console shows a note instead of a warning.
Install a license
Section titled “Install a license”Plenary reads the license from the first of these sources that has one:
| Priority | Source | Typical use |
|---|---|---|
| 1 | The PLENARY_LICENSE environment variable |
Container platforms, CI-driven deploys |
| 2 | The file named by license.file in plenary.yaml |
Mounted secrets |
| 3 | A license installed in the console | Manual installs |
A license from the environment or a file always wins over one installed in the console. Environment and file licenses are read at startup, so replacing one takes a restart (a redeploy). A license installed in the console takes effect immediately, without a restart.
Environment variable
Section titled “Environment variable”Store the token in your secret manager and inject it into the container. On Amazon ECS, reference it from the task definition:
{ "containerDefinitions": [ { "name": "plenary", "secrets": [ { "name": "PLENARY_LICENSE", "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:plenary/license" } ] } ]}With Docker Compose:
services: plenary: image: public.ecr.aws/plenarycms/plenary:v1.5.2 environment: PLENARY_LICENSE: ${PLENARY_LICENSE}Renewing is a secret update plus a redeploy.
License file
Section titled “License file”license: file: /run/secrets/plenary_licenseLeading and trailing whitespace in the file is ignored, so a trailing newline is fine.
Console
Section titled “Console”- Go to Admin Settings → License.
- Paste the token into License token, or use Upload new license file.
- Click Install.
The server validates the token fully before saving it. A token that would not activate here (wrong host, expired, damaged) is refused with the reason, and nothing is stored. Installing needs a super user.
When the active license comes from PLENARY_LICENSE or license.file, the install field is disabled and names the source; replace the license where it is managed.
The first-run setup wizard also offers an optional license step. You can skip it and install a license later.
curl -X PUT https://cms.example.com/api/v1/settings/license \ -H "Authorization: Bearer $PLENARY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"license\": \"$PLENARY_LICENSE\"}"On success the response is the new license state (see Read the license state).
| Error | HTTP | Cause |
|---|---|---|
license_managed_externally |
409 | The active license comes from the environment or a file. vars.source is env or file. |
license_missing |
422 | The license field is empty. |
| Any other license reason | 422 | The token would not activate on this server. |
invalid_content_type |
415 | The request is not application/json. |
When an instance is unlicensed
Section titled “When an instance is unlicensed”An instance is unlicensed when it has no license or its license fails any check. Unlicensed means the Free plan: the limits apply, and nothing is locked. The reason code says why the license is not active; GET /api/v1/license reports it with "tier": "free".
The console shows a banner when an installed license is not active, or when the instance is over the Free plan limits. No license at all is the Free plan’s normal state and shows no banner.
Installing a valid license through the console lifts the limits on the next request.
Expiry
Section titled “Expiry”An evaluation license stops working at its expires_at time, checked against the server clock in UTC on every request. There is no grace period; the instance drops to the Free plan. From 14 days before expiry, the console shows “The evaluation license expires in N days.”
A full license never expires. Its update window only decides whether a newer release is covered. If you upgrade to a release published after your window, that release runs on the Free plan with license_update_window_exceeded; roll back to a covered release or renew.
Health checks
Section titled “Health checks”GET /api/v1/health reports the license state but always returns 200 while the database is reachable, so a license problem never makes a load balancer restart your container:
{ "status": "ok", "database": "ok", "version": "1.0.0", "edition": "on-prem", "license": "expired", "tier": "free" }license is the reason without its license_ prefix, or ok; tier is free or full.
Read the license state
Section titled “Read the license state”GET /api/v1/license returns the current state. Any signed-in user and any private API key may read it; public keys may not.
{ "status": "ok", "tier": "full", "limits": { "sites": null, "forms": true, "sso": true, "graphql": true }, "usage": { "sites": 3 }, "kind": "evaluation", "customer": "Example Corp", "license_id": "9d3f0a1c-5c02-4a5b-9c6e-1f2a3b4c5d6e", "hosts": ["cms.example.com"], "issued_at": "2026-08-05T00:00:00Z", "expires_at": "2026-09-05T00:00:00Z", "updates_until": "2029-08-05T00:00:00Z", "release_date": "2026-08-05T00:00:00Z", "host": "cms.example.com", "source": "env", "enforced": true, "version": "1.0.0", "token": "plv1.eyJraWQ…"}| Field | Meaning |
|---|---|
status |
ok, or a license reason such as license_expired. |
tier |
full with a valid license, otherwise free. |
limits |
What the tier permits: sites as a number or null for unlimited, forms, sso and graphql as booleans. |
usage |
What the limits are measured against: every site. |
kind |
full or evaluation. |
customer |
The licensee’s name. |
license_id |
The license’s id. Quote it to support. |
hosts |
Permitted hosts. |
issued_at, expires_at |
Issue date; expiry for evaluation licenses. |
updates_until |
End of the update window, if any. |
release_date |
This server release’s date, compared with updates_until. Absent on development builds. |
host |
The hostname this server checks against, from server.public_url. |
source |
Where the license came from: env, file, database, or none. |
enforced |
false on localhost and 127.0.0.1, where licensing is not enforced. |
version |
This server’s release version. |
token |
The installed token, so the console can offer it as a download. Absent when none is installed. |
The console shows the same information under Admin Settings → License, including Supplied by (the source).
License reasons
Section titled “License reasons”Each failure has its own code, used in logs, in status, and in the 422 returned by an install. None of them refuses a request by itself; a request the Free plan refuses carries one of the three limit codes below.
| Code | Meaning | What to do |
|---|---|---|
license_missing |
No license in any source. | Install one. |
license_malformed |
The token is damaged: bad prefix, bad encoding, or inconsistent fields. | Copy it again as one complete line. |
license_unsupported_version |
The license format is newer than this server understands. | Upgrade Plenary. Do not request a new license. |
license_unknown_key |
The license was signed with a key this server does not know, usually an older server with a newer license. | Upgrade Plenary, or contact support. |
license_signature_invalid |
The signature does not verify. The token was altered or truncated. | Copy it again exactly as issued. |
license_host_mismatch |
The license does not permit this server’s public_url hostname. |
Check server.public_url, or request a license for this host. |
license_expired |
An evaluation license is past its expiry. | Install a full license or a renewed evaluation. |
license_update_window_exceeded |
This release was published after the license’s update window. | Run a release inside the window, or renew the license. |
| Code | Meaning | What to do |
|---|---|---|
license_limit_sites |
Creating this site would exceed the Free plan’s one site. vars.limit, vars.count. |
Install a license. |
license_feature_forms |
Forms are not included in the Free plan. On a metadata import, vars.forms names the files. |
Install a license. |
license_feature_sso |
Single sign-on is not included in the Free plan. | Install a license. |
license_feature_graphql |
The GraphQL API is not included in the Free plan. | Install a license. |
Verify a license offline
Section titled “Verify a license offline”Validation never needs the network. The plenary command shipped in the image checks a token the same way the server does, without a database or a running instance, so a pipeline can catch a bad license before deploying. Run it from the image you are about to deploy:
docker run --rm --entrypoint plenary public.ecr.aws/plenarycms/plenary:v1.5.2 \ license verify --license "$PLENARY_LICENSE" --host cms.example.com --min-days 14Running it from that image matters for the update window: verify compares the license against the release date of the binary it runs in, so this checks the exact release you are shipping.
| Command | Flags |
|---|---|
plenary license show |
--license <token> or --file <path>. Prints the license’s claims. |
plenary license verify |
--license <token>, --file <path>, or --config <path> (reads the token and host from a plenary.yaml); --host <hostname>; --min-days <n> fails if the license expires within n days. |
With no --license or --file, both commands read PLENARY_LICENSE. verify prints license ok, the claims and the tier, or exits non-zero with the reason.
This is not the @plenary/cli npm package, which has no license commands.
Plenary Cloud
Section titled “Plenary Cloud”Plenary Cloud instances do not use license tokens. GET /api/v1/license and PUT /api/v1/settings/license answer 403 cloud_managed, /api/v1/health has no license field, and the console shows Subscription instead of License. See Plenary Cloud.
Related
Section titled “Related”- Self-hosted: installing and configuring a self-hosted instance.
- Settings:
plenary.yamlversus console settings. - Errors: every error code.