Roles

Pro Feature

Roles are named bundles of permissions you assign to users and user groups — Editors, Authors, Clients, whatever fits your team.

Hot Tip!

Need the list of built-in abilities? That's Permissions. Registering your own in PHP? See Custom Permissions.

Overview#

A user has no Control Panel abilities on their own. You grant access by assigning roles, and each role is a named set of permissions.

Think of it as a stack:

1. Permissions — individual abilities (edit blog entries, access cp, …)
2. Roles — packages of those abilities ("Editor", "Publisher")
3. Users / groups — who gets which roles

Roles are managed in the Control Panel under Users → Roles, and stored in resources/users/roles.yaml.

Creating roles#

Create and edit roles in the Control Panel, or by hand in YAML:

# resources/users/roles.yaml
editor:
  title: Editor
  permissions:
    - access cp
    - view blog entries
    - edit blog entries
    - create blog entries
    - publish blog entries

Pick permissions from the native list, or from custom ones you've registered.

Assigning roles#

Attach roles to individual users, or to a user group so every member inherits them.

On a user YAML file:

roles:
  - editor
  - publisher

In the Control Panel: open the user (or group) and pick roles from the list. Prefer groups when you have more than a handful of people with the same access — assign the role once on the group instead of per user.

In blueprints#

Need a field that picks roles? Use the User Roles fieldtype.

On the frontend#

Check the current user's roles with {{ user:is }}, or list roles with {{ user:roles }}.

Super users#

Super users bypass roles and permissions entirely. They can do everything — including create more super users. Keep that circle small.