Skip to content

Permissions

This page is the complete permission catalog for a Plenary instance and the rules that evaluate it. Use it when you author a role or decide what a private API key should hold. For a task-oriented walkthrough, see Users & Permissions and API Keys.

Three kinds of principal can call the API, and they get their access in different ways:

  • A super user passes every check on every site and holds no grants. Managing users and roles, creating and deleting sites, global settings, the license, and instance-wide API keys are a super user’s alone; no capability reaches them. See Super users.
  • Any other user holds one role per site. A role belongs to one site, and its grants reach that site and nothing else. There are no direct grants on a user.
  • An API key belongs to one site, or, for a private key a super user creates, to the whole instance. A private key holds its own grants; a public key holds none. See API key ceilings.

Plenary authorizes every request on the server. The rules are short:

  • Deny by default. A principal (a signed-in user or an API key) can do nothing until a grant allows it, unless it is a super user.
  • Allow-only grants. A grant names one capability and, optionally, narrows it to a site, a content model, or both. There are no deny rules and no exceptions.
  • Union. A principal’s effective access is the union of every grant it holds. For a user, that is the grants of each of their site roles, each limited to its site. Adding a grant can only add access.
  • Every filter must match. A grant applies to a request only when every filter it sets matches the request. A grant with a site filter never satisfies a request that has no site, and a grant with a model filter never satisfies a request about a different model.
  • No wildcards. Every grant key must exactly match a capability in the catalog. content:* is rejected with role_grant_key_invalid_format.
  • Resolved from the database. A user’s access token identifies them, but permissions are always read from the stored roles and user. Changing a role or a user takes effect on that user’s next request.

In one sentence: a principal may do X if and only if it is a super user, or some grant it holds names capability X and every filter that grant sets matches the request.

Roles and API keys store grants in the same shape. When you write a grant through the API, you name the content model by its key:

{
"key": "content:entries:update",
"site_key": "marketing",
"content_model_key": "blog_post"
}
Field Required Meaning
key Yes A capability string from the catalog.
site_key No Limits the grant to one site. Every capability accepts it. On a role, leave it out: the role’s own site applies, and naming another site is 422 role_scope_not_allowed. On a site-bound API key it is filled in with the key’s site.
content_model_key No Limits the grant to one content model or form, named by its key. Allowed only on capabilities whose Filters column includes model. Model keys are unique within a site, so the model is looked up on the grant’s site (the role’s or key’s site, or site_key). On an instance-wide key, a key that two sites use needs site_key (422 model_site_key_required).

On an instance-wide private key, a grant with neither filter is global for its capability and reaches every site, including sites created later. A grant can set both filters: “update entries of blog_post, only on site marketing” is one grant.

Plenary stores the model filter as the model’s internal id, so two read surfaces show an id instead of a key:

  • GET /api/v1/auth/me returns each grant as {key, site_key?, content_model_id?, source}; see Check what a caller holds.
  • When the model a grant names has been deleted, role and API key detail responses return that grant with content_model_id (the dead id) in place of content_model_key. The grant can never match again. Remove it and save; the console will not save until you do.

Validation when you write grants:

Problem Error (HTTP 422)
key is not shaped like domain:resource:action (lowercase, colon-separated) role_grant_key_invalid_format
key is not in the catalog role_grant_keys_invalid
The capability does not accept a filter you set, or a role’s grant names another site or another site’s model role_scope_not_allowed
The site or model a filter names does not exist role_scope_target_not_found
Two grants have the same key and filters role_grant_duplicate
A site-bound API key’s grant names another site api_key_grant_site_mismatch

The role_ codes keep their prefix on the API key endpoints too.

The instance writes this catalog at every startup, so it always matches the running release. GET /api/v1/permissions returns it; see Read the catalog. There are 30 capabilities.

Every capability accepts a site filter, because everything it guards belongs to a site. Filters lists which filters a capability accepts: site (site_key) and, for most content capabilities, model (content_model_key).

Capability What it allows Filters
content:entries:read Read content entries, including drafts, private models, and private fields. site, model
content:entries:create Create content entries. site, model
content:entries:update Update content entries. Restoring an entry from revision history is an update. site, model
content:entries:delete Archive content entries, or delete them permanently with their history (?permanent=true). site, model
content:entries:publish Publish and unpublish content entries. site, model
content:revisions:read Read revision history for entries, models, and forms. site, model
content:webhooks:manage Create, edit, and delete webhooks. A site’s own webhooks need this capability without a model filter. site, model
content:transformers:manage Create, edit, and delete transformers. site, model
Capability What it allows Filters
content:models:read Read content model definitions. site, model
content:models:create Create content models. The model’s site_key is checked. site, model
content:models:update Update content models. site, model
content:models:delete Delete content models. site, model

GET /api/v1/models, /forms, and /objects list only the models on sites your grants cover; a ?site_key= outside them is 403 permission_denied.

Capability What it allows Filters
content:forms:read Read form definitions. site, model
content:forms:create Create forms. site, model
content:forms:update Update forms. site, model
content:forms:delete Delete forms. site, model
content:form_entries:read Read form entries. Also lists and reads the form definitions those entries need. site, model
content:form_entries:update Triage form entries (change their status). site, model
content:form_entries:delete Delete form entries. site, model

A model filter on a form names the form’s key, so {"key": "content:form_entries:read", "content_model_key": "contact"} reaches exactly one form.

Capability What it allows Filters
content:media:read Read media assets and media folders, including signed URLs for private assets. site
content:media:create Upload media assets. site
content:media:update Update media metadata, manage media folders, move assets between folders, and change asset visibility. site
content:media:delete Delete media assets. site

Each site has its own media library, so media capabilities are checked at the asset’s or folder’s site. They accept no model filter.

Capability What it allows Filters
admin:api_keys:read List and read the site’s API keys. site
admin:api_keys:create Create API keys on the site. site
admin:api_keys:update Update, deactivate, and revoke the site’s API keys. site
admin:api_keys:delete Delete the site’s API keys. site

These reach the keys that belong to the site only. A key manager on one site can neither create a key on another site nor move one there (403 permission_denied). Instance-wide keys are a super user’s.

Capability What it allows Filters
admin:sites:update Update the site’s own settings: name, description, active state, locales, timezone, and config. Site webhooks need content:webhooks:manage instead. site
admin:metrics:read Read the site’s dashboard metrics. site
  • Listing sites. Every authenticated principal can read GET /api/v1/sites.
  • Submitting a form. POST /api/v1/forms/{form_key}/entries accepts any valid API key, a public key included.
  • Your own account. Every signed-in user can edit their own contact details and password (/api/v1/me/account, /api/v1/me/password) and read their preferences.
  • Looking up people for a user field. GET /api/v1/users/lookup returns a minimal profile (no email address) to any signed-in user. API keys cannot call it.
  • Grant-authoring reference data. GET /api/v1/permissions and GET /api/v1/scope-targets are open to every user session and private key. See Read the catalog.

These are not capabilities. No grant can reach them, and anyone else gets 403 permission_denied:

  • managing users (/api/v1/users) and roles (/api/v1/sites/{site_key}/roles);
  • creating and deleting sites (POST /api/v1/sites, DELETE /api/v1/sites/{site_key});
  • instance settings (/api/v1/settings/*), installing a license, and reading monthly usage (/api/v1/usage);
  • creating, reading, changing, and deleting an instance-wide API key.

These are deliberately absent. A grant naming one is rejected:

  • admin:sites:read: listing sites is open, see above.
  • admin:users:*, admin:roles:*, admin:sites:create, admin:sites:delete, admin:settings:manage: a super user’s, see above.
  • content:form_entries:create: submitting a form is open, see above.
  • content:revisions:restore: restoring an entry is content:entries:update.
  • Any wildcard, such as content:* or admin:api_keys:*.

How a filter is checked depends on the route:

  • Routes that target one entry (update, delete, publish, form-entry triage) load the entry and check its actual model and site.
  • Writes that name their site (POST /api/v1/content/{model_key}?site_key=…, bulk move, content folder routes) check the site in the request. Omitting site_key fails a site-filtered grant.
  • Reads that can span sites (GET /api/v1/content/{model_key}, form-entry lists, single-entry reads by slug or id) narrow the result to the sites your grants allow:
    • a list returns only entries on sites you may read;
    • an explicit ?site_key= outside your grants returns 403 permission_denied;
    • if your grants allow no site for that model, the list returns 403, not an empty list;
    • a single entry on a site you cannot read returns 404, the same as a missing entry.
  • Revision history checks the model and site recorded on each revision, so the history of a deleted entry stays readable to whoever could read the entry.

A role’s grants always carry its site. Only an instance-wide private key can hold a grant with no site filter, and that grant reaches every site, including sites created later.

API keys are issued to integrations and never hold a role. A private key’s grants use the same shape and rules as a role’s. Each key type has a ceiling:

Key type Secret prefix Grants allowed Site
public pln_pub_ None. A grant on a public key is rejected with 422 api_key_grants_not_allowed. Required: site_key names the one site it reads (422 api_key_sites_required).
private pln_prv_ content:* capabilities only, with any filters they accept. An admin:* capability is rejected with 422 api_key_grant_not_allowed, and vars.capabilities lists the offending keys. Optional. With a site_key, every grant is held to that site. Without one, the key is instance-wide and only a super user may manage it.

A public key has a fixed, read-only view of its site that does not depend on the catalog:

  • published entries on the key’s site, or drafts too if the key has include_drafts;
  • only models and fields not marked private (hidden from the public API); a private model answers 404;
  • form definitions through GET /api/v1/forms/{form_key};
  • submitting form entries;
  • single media documents of the key’s site through GET /api/v1/media/{media_id}, except private assets, which answer 404.

Every capability-gated route refuses a public key with 403 permission_denied. Revision history refuses public keys outright.

A private key with content:entries:read sees private models and private fields in full, the same as a signed-in user. A request from a site-bound key that names no site uses the key’s site. Keep private keys on the server. See API Keys.

Nothing under admin:* is reachable with an API key. Managing keys, sites, users, roles, and settings requires a person signed in with a user session.

Every site gets four roles: when it is created, through the API or a metadata import, and at startup for a site that has none. Their grants carry no site filter of their own; they reach the role’s site.

Role key Name Grants
admin Admin Every capability in the catalog. A system role: it cannot be edited or deleted (403 role_system_protected), and it is reset to the full catalog at every startup, so it gains capabilities added by an upgrade.
developer Developer Every content:* capability, plus admin:api_keys:read, admin:api_keys:create, admin:api_keys:update, and admin:api_keys:delete.
editor Editor content:models:read, content:forms:read, content:entries:read, content:entries:create, content:entries:update, content:entries:publish, content:entries:delete, content:form_entries:read, content:form_entries:update, content:form_entries:delete, content:media:read, content:media:create, content:media:update, content:media:delete, content:revisions:read.
reviewer Reviewer content:models:read, content:entries:read, content:entries:publish, content:media:read, content:revisions:read.

developer, editor, and reviewer are starter roles: created only when the site has no roles, then ordinary roles you can edit or delete. Startup never re-creates or resets them, so they do not gain capabilities added in later releases.

GET /api/v1/permissions returns the catalog, sorted by group and key. Any signed-in user or private API key may call it; a public key gets 403.

Terminal window
curl https://your-instance.plenarycms.io/api/v1/permissions \
-H "Authorization: Bearer $PLENARY_ACCESS_TOKEN"
[
{
"key": "content:entries:create",
"description": "Create content entries",
"group_key": "content",
"model_scoped": true
},
{
"key": "admin:metrics:read",
"description": "Read dashboard metrics",
"group_key": "system",
"model_scoped": false
}
]

group_key is one of content, content_modeling, forms, iam, media, or system. model_scoped says whether the capability accepts a model filter; every capability accepts a site filter.

GET /api/v1/scope-targets (open to the same callers) returns what a filter may name: every site, inactive ones included, and every content model and form with the site that owns it. Object models are left out because they hold no entries.

{
"sites": [
{ "key": "marketing", "name": "Marketing", "is_active": true }
],
"content_models": [
{ "key": "blog_post", "name": "Blog Post", "kind": "collection", "site_key": "marketing" },
{ "key": "contact", "name": "Contact", "kind": "form", "site_key": "marketing" }
]
}

GET /api/v1/auth/me returns the caller’s resolved grants. For a user session:

{
"principal": "user",
"user_id": "4b87b0bb-25a8-4d7e-a025-e5dd3a7faa28",
"is_super_user": false,
"grants": [
{ "key": "content:entries:update", "site_key": "marketing", "source": "site_role", "role_key": "editor" },
{ "key": "content:form_entries:read", "site_key": "marketing", "content_model_id": "75292dcf-44ec-4577-930f-4e366fffe08e", "source": "site_role", "role_key": "forms_reader" }
],
"sites": [
{ "key": "marketing", "name": "Marketing", "default_locale": "en-us", "locales": ["en-us"], "timezone": "UTC" }
],
"sms_enabled": true
}

Each grant names the site role it comes from (role_key) and that role’s site. sites lists the active sites where the caller holds a role that grants anything; it feeds the console’s site selector. A super user gets "is_super_user": true, an empty grants list, and every active site.

For an API key the response is {principal: "api_key", key_id, key_type, name, grants, site_key}, with source: "key" on every grant. site_key is the key’s site, or "" for an instance-wide key.

Roles belong to a site and are managed by super users only. Every path names the site; an unknown site is 404 site_not_found.

Method Path Notes
GET /api/v1/sites/{site_key}/roles The site’s roles, each with assigned_user_count: the users holding it on that site.
GET /api/v1/sites/{site_key}/roles/{role_key} One role and its grants.
POST /api/v1/sites/{site_key}/roles Body {key, name, description?, grants}. The key is unique within the site (409 role_key_taken).
PUT /api/v1/sites/{site_key}/roles/{role_key} Body {name, description?, grants}; replaces the grant list.
DELETE /api/v1/sites/{site_key}/roles/{role_key}

A role’s key is immutable, and PUT ignores a key in the body. The site’s admin role cannot be changed or deleted (403 role_system_protected). A role still assigned to users cannot be deleted: DELETE returns 409 role_in_use with vars.users, the number of users holding it. Users are given a role on a site through site_roles on the user API.