Skip to content

Users & Permissions

Every person who signs in to the console is a user. A user’s access is one of two things: the super user flag, which passes every check and alone manages users, roles, sites, and global settings; or a role per site, where each role is a named list of grants that reach that site and nothing else. A grant allows one capability, optionally narrowed to one content model or form. Use this page to invite people, choose their access, and build roles for common team setups.

Access is deny-by-default and allow-only: a user can do only what some grant allows, and nothing can take access away except removing a grant or a role. The full capability list is in the Permissions reference.

A user is an account, not content. Its fields are fixed on every Plenary instance:

Field Notes
username Unique. Stored in lowercase. The sign-in handle; it cannot be changed in the console after the user is created.
email Unique. Required. Invitations, password resets, and email sign-in codes go here.
sms_phone Unique when set. E.164 format (+15551234567). Used for SMS sign-in codes. The console accepts a US number such as (415) 555-0192.
first_name, last_name Required.
display_name Optional. Shown instead of the full name across the console.
avatar Optional image from the Media Library.
is_active An inactive user cannot sign in. Turning it off signs them out everywhere; their content and history stay.
is_email_verified, is_sms_phone_verified Sign-in codes go only to verified destinations.
is_2fa_enabled Require a one-time code at sign-in.
is_super_user Full access everywhere, plus user, role, site, and settings management. See Super users.
site_roles The user’s role on each site, as [{ "site_key", "role_key" }], at most one per site. See Site access.
identities Identity-provider links, written only by single sign-on. See Single sign-on users.

You cannot add custom fields to users. To store more about a person (a job title, a bio, a department), create a content model with a user field that points at the account, such as a staff_profile collection with account, job_title, and bio fields. That model gets revision history, publishing, site scoping, and Content API delivery like any other.

Only a super user can manage users. Under Access Management → Users:

  1. Click New user.
  2. Fill in Email, Username, First name, and Last name. Display name, SMS phone, and Avatar are optional.
  3. Choose the access. Either turn on Super user, or leave it off and pick a role for each site in the Site access card. A site left at No access is one the user cannot see.
  4. Leave Active on create on unless the account should wait.
  5. Click Create & send invite.

Plenary emails the user a link to set their own password. The link is valid for 24 hours. Email sending must be configured first; see Settings. An email address or phone number that an administrator enters is marked verified automatically.

To create a user through the API, POST /api/v1/users as a super user. Send "password": null and "password_reset_required": true to email the same set-password link:

Terminal window
curl -X POST https://your-instance.plenarycms.io/api/v1/users \
-H "Authorization: Bearer $PLENARY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "jsmith",
"email": "jsmith@example.com",
"first_name": "Jane",
"last_name": "Smith",
"is_active": true,
"is_super_user": false,
"site_roles": [
{ "site_key": "marketing", "role_key": "editor" },
{ "site_key": "docs", "role_key": "reviewer" }
],
"password": null,
"password_reset_required": true
}'

PUT /api/v1/users/{id} replaces the user’s profile fields, so send every field each time, is_super_user included. Its site_roles array is optional: omit it to keep the user’s roles, or send [] to clear them. Each entry must name an existing site and a role on that site (422 user_site_role_site_not_found, user_site_role_role_not_found), and a site may appear once (422 user_site_role_duplicate).

A super user passes every permission check on every site and is the only kind of user who can:

  • manage users and roles;
  • create and delete sites;
  • change Global Settings, install a license, and read usage;
  • see the instance-wide counts on the dashboard;
  • create and manage an instance-wide API key, one that belongs to no site.

The console hides Users, Roles, Global Settings, License, and Subscription from everyone else. No role or grant can reach those pages or their endpoints. Setup makes the first user a super user.

An instance always keeps at least one active super user. You cannot change your own Super user switch, deactivate yourself, or delete yourself (403 user_super_user_self, user_deactivate_self, user_delete_self), and nobody can clear the flag on, deactivate, or delete the last active super user (409 user_last_super_user). The console disables those controls when you are editing yourself.

A super user’s site roles are kept but idle while the flag is on, and apply again if it is turned off.

A user who is not a super user gets their access from the Site access card: one role per site, chosen from that site’s own roles. A role’s grants reach its site only, so Admin on a site is full access to that one site, including its API keys and site settings, and nothing on any other site and no user or role management. A user with no role on a site cannot see it; the console’s site selector lists only the sites where the user holds a role.

The user list’s Access column summarises this, with a Super user pill or the sites the user reaches, and the filter narrows the list to super users.

Open the user and use Set status to make them inactive. They are signed out everywhere and cannot sign in, and their content and history stay. This is the usual way to remove access.

Deleting is permanent. The console asks you to type the user’s email address. Through the API, pass the address as email_confirm: DELETE /api/v1/users/{id}?email_confirm=jsmith@example.com. You cannot delete yourself, and the last active super user cannot be deleted or deactivated.

Turn on Two-factor auth in the Security group of a user’s Details tab. At sign-in, after the password, Plenary sends a 6-digit code that expires in 10 minutes. The code goes to the user’s verified email address or verified SMS phone; when both are available, the user chooses.

SMS codes need an SMS provider; see Settings. While no SMS provider is configured, the console hides the 2FA switch and the SMS phone field. Users cannot turn 2FA on or off for themselves. For the sign-in API, see Authentication.

When the instance is connected to an identity provider (see Single sign-on), people can sign in with Continue with single sign-on instead of a password. The first such sign-in links the provider’s identity to the user’s account, matched by verified email address; or, if the connection creates accounts on first sign-in, it creates the user with the connection’s default role per site.

A user’s Details tab shows what that produced:

  • Linked identities lists each provider the account is linked to, with the provider’s identifier for the person, the email at the time of linking, and the link date. Unlink removes one; the person can no longer sign in through that provider until a verified-email match links them again. It changes nothing else about the account.
  • The Password row reads SSO ONLY for an account that was created by single sign-on and has no password. Send set-password link emails the usual set-password link, which gives the person a password as a fallback.

Single sign-on never changes a user’s site roles or super user status. When the connection has Require single sign-on on, everyone but a super user must sign in through the provider; super users keep their password as the fallback. Through the API, the identities are on GET /api/v1/users/{id} as identities, with has_password; DELETE /api/v1/users/{id}/identities/{provider_key} unlinks one.

A user can sign in with a passkey instead of a password and code: Touch ID, Face ID, Windows Hello, a hardware security key, or a passkey synced by a password manager. The passkey’s own unlock counts as the second factor, so no one-time code is sent. Passkeys are available on every plan and need no setting; the sign-in page shows Sign in with a passkey in any browser that supports them.

Only the user can enrol one, because the browser creates it on their own device: in Account Settings → Passkeys, click Add a passkey, give it a name you will recognise, and follow the browser’s prompt. The card lists each passkey with when it was added and last used; Rename and Remove act on one. Removing a passkey does not sign the user out anywhere; it only stops that device signing in. The password stays and works as before.

A super user sees a user’s passkeys in the Passkeys card of the user’s Details tab and can Remove one, for a lost or stolen device. There is no way for an administrator to add a passkey to someone else’s account. Through the API, the passkeys are on GET /api/v1/users/{id} as passkeys; DELETE /api/v1/users/{id}/passkeys/{passkey_id} removes one. The sign-in API is on Authentication.

When the instance has Require single sign-on on, passkeys are closed to everyone but a super user, like passwords.

Each user manages their own account from Account Settings in the account menu. They can change:

  • Display name and Avatar;
  • Email and SMS Phone: a changed email address is marked unverified and Plenary emails a confirmation link valid for 30 minutes; a changed phone number is marked unverified;
  • their Password: changing it signs them out on every other device;
  • their Passkeys: add, rename, or remove one (see Passkeys).

Username, first name, and last name are shown but read-only. The super user flag, site roles, active status, and 2FA can only be changed by a super user.

Every signed-in user has this page; it needs no grant. Changing the avatar also needs content:media:read on some site, because the picker browses the Media Library; without it the avatar is shown read-only with a note to ask an administrator.

The same actions are available through the API at GET and PUT /api/v1/me/account, PUT /api/v1/me/password, and /api/v1/me/passkeys. These routes take no user id; they always act on the caller.

A role is a named list of grants that belongs to one site. Its grants reach that site and nothing else, so the same key, such as editor, can mean different things on different sites. Only a super user manages roles, under Access Management → Roles, where the rail lists every site’s roles.

Every site gets four roles when it is created:

Role For Can
Admin People who run the site Everything on the site: content, models, forms, media, webhooks, transformers, API keys, and the site’s own settings.
Developer People who build and integrate the site All content work, including models, forms, webhooks, and transformers, plus managing the site’s API keys.
Editor Day-to-day content staff Create, edit, publish, and delete entries; manage media; triage form entries; read models, forms, and history.
Reviewer People who approve content Read entries, models, media, and history, and publish entries.

Admin is a system role: it cannot be edited or deleted, and Plenary resets it to every capability at each startup, so a capability added in a release reaches every site’s Admin on upgrade. Developer, Editor, and Reviewer are starter roles: created with the site, then ordinary roles you can edit or delete. The exact grant lists are in the Permissions reference.

  1. Go to Access Management → Roles and click New.
  2. Choose the Site the role belongs to. It cannot be moved to another site later.
  3. Enter a Name and a Key. The key is a stable identifier, such as blog_writer, unique within the site, and cannot be changed after the role is created.
  4. Optionally add a Description.
  5. Tick the capabilities the role should have in the grant matrix. Rows are resources (Entries, Models, Media, Forms, Form entries, and so on); columns are verbs (Read, Create, Update, Delete, Publish, Manage).
  6. To narrow a row to particular models or forms, open its Scope cell and choose Selected models or Selected forms. The scope applies to every verb ticked on that row. Leave the Sites axis at All sites: the role already belongs to one site, and a grant naming another site is refused.
  7. Click Create Role.

To rename a role’s key, create a new role, move its users to it, then delete the old one. A role that users still hold cannot be deleted (409 role_in_use).

Through the API, POST /api/v1/sites/{site_key}/roles as a super user:

Terminal window
curl -X POST https://your-instance.plenarycms.io/api/v1/sites/marketing/roles \
-H "Authorization: Bearer $PLENARY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "blog_writer",
"name": "Blog Writer",
"description": "Writes and publishes the blog on the marketing site.",
"grants": [
{ "key": "content:models:read", "content_model_key": "blog_post" },
{ "key": "content:entries:read", "content_model_key": "blog_post" },
{ "key": "content:entries:create", "content_model_key": "blog_post" },
{ "key": "content:entries:update", "content_model_key": "blog_post" },
{ "key": "content:entries:publish", "content_model_key": "blog_post" },
{ "key": "content:media:read" },
{ "key": "content:media:create" }
]
}'

Roles can also live in version control as YAML; see Models as Code.

A grant is one capability, optionally narrowed to one content model or form:

{ "key": "content:entries:update", "content_model_key": "blog_post" }
  • key is a capability such as content:entries:update.
  • content_model_key limits the grant to one content model or form on the role’s site.

A grant with no filter applies to everything of its kind on the site, including models created later. A role’s grants carry no site filter of their own: the role’s site is applied when the user signs in, and the API reads each grant back with site_key filled in. Not every capability accepts a model filter:

  • Entries, form entries, revisions, and the model, form, webhook, and transformer definitions accept one.
  • Media accepts none; each site has its own Media Library, and a media grant covers all of it.
  • The admin:* capabilities a role may hold, for API keys, site settings, and dashboard metrics, accept none.

A model filter on a capability that does not accept one is refused with 422 role_scope_not_allowed, as is a filter naming a model that belongs to another site.

There are no direct grants on a user and no deny rules. If one person needs more than their role gives, assign them a different role or create one; if they need less, make a narrower role. GET /api/v1/auth/me returns the caller’s resolved grants, each labelled with source: "site_role", its site_key, and the role_key it comes from, so you can see where access comes from.

The first two setups need no custom role. The others are roles you create on the site in question; replace marketing, blog_post, and contact with your own site, model, and form keys.

In the user’s Site access card, set Editor on marketing and leave every other site at No access. The console’s site selector shows only that site; the Media Library the editor sees is that site’s; asking for another site’s entries through the API returns 403 permission_denied, and a single entry from another site returns 404.

Set Admin on the site. That is full access to the site, including its API keys, webhooks, transformers, and site settings, but no access to any other site and no user, role, or global settings management. For those, the person needs the Super user switch.

Contributor who drafts but does not publish

Section titled “Contributor who drafts but does not publish”

A writer who creates and edits drafts for someone else to publish. Create a role on the site with the Editor grants but leave out content:entries:publish (and content:entries:delete if they should not delete). Pair them with the Reviewer role, or an editor, who publishes.

Capability Filter
content:models:read, content:forms:read none
content:entries:read, content:entries:create, content:entries:update none, or content_model_key to limit them to some models
content:revisions:read none
content:media:read, content:media:create, content:media:update none

Someone who reads the entries of one form, for example a sales team member who follows up on the contact form, and nothing else. Create this role on the site the form belongs to:

Capability Filter
content:form_entries:read content_model_key: contact
content:form_entries:update content_model_key: contact (optional: lets them mark entries read, archived, or spam)

content:form_entries:read also lets them see the form’s definition, so no content:forms:read grant is needed. An Editor on the site already holds both capabilities for every form there.