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.
Who holds grants
Section titled “Who holds grants”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.
Evaluation rules
Section titled “Evaluation rules”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 withrole_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.
Grant shape
Section titled “Grant shape”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/mereturns 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 ofcontent_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.
Capability catalog
Section titled “Capability catalog”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).
Content
Section titled “Content”| 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 |
Content modeling
Section titled “Content modeling”| 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.
API keys
Section titled “API keys”| 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 |
Actions that need no capability
Section titled “Actions that need no capability”- Listing sites. Every authenticated principal can read
GET /api/v1/sites. - Submitting a form.
POST /api/v1/forms/{form_key}/entriesaccepts 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
userfield.GET /api/v1/users/lookupreturns a minimal profile (no email address) to any signed-in user. API keys cannot call it. - Grant-authoring reference data.
GET /api/v1/permissionsandGET /api/v1/scope-targetsare open to every user session and private key. See Read the catalog.
What only a super user can do
Section titled “What only a super user can do”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.
Capabilities that do not exist
Section titled “Capabilities that do not exist”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 iscontent:entries:update.- Any wildcard, such as
content:*oradmin:api_keys:*.
How filters apply to requests
Section titled “How filters apply to requests”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. Omittingsite_keyfails 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 returns403 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 key ceilings
Section titled “API key ceilings”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 answer404.
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.
Seeded roles
Section titled “Seeded roles”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.
Read the catalog
Section titled “Read the catalog”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.
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" } ]}Check what a caller holds
Section titled “Check what a caller holds”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.
Role endpoints
Section titled “Role endpoints”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.
Related
Section titled “Related”- Users & Permissions: super users, site roles, and common setups.
- API Keys: issuing and using public and private keys.
- Errors: every error code.