Skip to content

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.

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.

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.

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.com or a wildcard such as *.staging.example.com. A wildcard matches exactly one label in the leftmost position: *.staging.example.com matches pr-12.staging.example.com but not a.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.

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.

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.

Store the token in your secret manager and inject it into the container. On Amazon ECS, reference it from the task definition:

task-definition.json
{
"containerDefinitions": [
{
"name": "plenary",
"secrets": [
{
"name": "PLENARY_LICENSE",
"valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:plenary/license"
}
]
}
]
}

With Docker Compose:

compose.yaml
services:
plenary:
image: public.ecr.aws/plenarycms/plenary:v1.5.2
environment:
PLENARY_LICENSE: ${PLENARY_LICENSE}

Renewing is a secret update plus a redeploy.

plenary.yaml
license:
file: /run/secrets/plenary_license

Leading and trailing whitespace in the file is ignored, so a trailing newline is fine.

  1. Go to Admin Settings → License.
  2. Paste the token into License token, or use Upload new license file.
  3. 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.

Terminal window
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.

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.

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.

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.

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).

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.

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:

Terminal window
docker run --rm --entrypoint plenary public.ecr.aws/plenarycms/plenary:v1.5.2 \
license verify --license "$PLENARY_LICENSE" --host cms.example.com --min-days 14

Running 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 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.

  • Self-hosted: installing and configuring a self-hosted instance.
  • Settings: plenary.yaml versus console settings.
  • Errors: every error code.