Manage users, roles and permissions
Each teammate holds a role with only the permissions their job needs, and you can suspend or ban any account.
Access is role based. A user holds roles, and each role grants permission keys. Opening /admin needs admin.access. Every admin page then checks its own permission, so a teammate's roles determine which pages they see.
Before you begin
- A first administrator created with
pnpm db:bootstrap-super-admin. See First steps after install. - To create roles you need
roles.write. To assign roles or change a user's status you needusers.write. - The full permission catalog, with a description of each key, is at
/admin/permissions.
Create a role
As a rule, a .read permission opens a page and the matching .write permission allows changes on it.
Open the role form
Go to Operations → Roles (/admin/roles) and open the Add role tab.
Start from a preset (optional)
Under Sidebar role presets, click a preset to fill the form. The presets are Admin Overview, Admin Operations, Commerce Manager, Platform Operator, Content Manager, Security Manager and Settings Manager. Roles with the same keys already exist and can be assigned directly.
Describe the role
Fill in Key (a stable identifier such as support.lead), Name and Description. All three are required.
Pick the permissions
Under Permissions, tick the permissions to grant. They are grouped by sidebar area: Overview, Operations, Commerce, Platform, Content, Security, Settings and Other. Always include admin.access.
Save
Click Save role.
To change a role later, open the Roles & users tab and click Edit on its row in Role directory. Delete works only while no user holds the role. The full catalog with descriptions is at /admin/permissions (Permission catalog, no sidebar entry).
Assign roles to a user
Find the user
Go to Overview → Users (/admin/users/dashboard), find the user and click their name or Details.
Check the status
Under Access, Status must be Active. A pending or banned user gets no permissions from any role.
Choose the roles
In the Roles card, click Roles. In the Update user roles dialog, tick the roles to grant and untick the ones to remove, then click Save roles.
Users who already hold a role also appear under Role users on /admin/roles, where Update roles opens the same dialog.
Suspend or ban a user
Open the user
On Overview → Users, click Details on the user.
Set the status
Set Status to Active, Pending or Banned. For a ban, add an optional Ban reason and Ban expires date.
Save
Click Save. The page confirms the change and records it in the audit log.
A banned user cannot sign in, their pages send them to /system/permission-denied, and their API keys stop working. Once Ban expires has passed, the account is treated as active again. A pending user is sent to /system/session-expired.
Changes apply without signing out
Role and status changes take effect on the user's next page load. The user does not need to sign in again.
Verify
Sign in as the user in a private window. The sidebar shows only the pages their roles allow, and a page opened by URL without its permission shows Permission denied: <permission>. Security → Audit (/admin/audit) lists the status change. From the command line, pnpm validate:users checks role saving, assignment and status changes.
Troubleshooting
/admin redirects to /system/permission-denied
The user lacks admin.access. Assign a role that includes it, or run pnpm db:bootstrap-super-admin for the first administrator.
A page shows Permission denied: <permission>
The user can open the console but lacks the permission that page checks. The dashboard at /admin needs four: admin.dashboard.read, users.read, credits.read and ai.read, so a narrow role sees this error there.
A user with the right role still has no access
Their Status is pending or banned. Set it to Active on the user's page.
A new permission does not reach the Super Admin
Role permissions are written when pnpm db:bootstrap-super-admin runs. Run it again after an upgrade that adds permissions.