Admin Roles
Create and manage admin roles, assign permissions to them, and control which admin users hold each role.
Overview
Admin roles let administrators delegate specific sections of the admin panel to team members without granting full system access. Each role carries a set of granular permissions and can be assigned to any number of admin users.
Accessing the Page
Navigate to Admin > Admin Roles (/admin-roles). Both the sidebar entry and the page itself require admin-roles:read, on top of the admin:access dashboard gate.
The list is a table with Name, Permissions (count), Members (count), Type (System / Custom badge), and Actions.
Permissions
| Permission | Description |
|---|---|
admin-roles:read | View the admin roles list |
admin-roles:create | Create new admin roles |
admin-roles:edit | Edit existing roles (name, description, permissions, members) |
admin-roles:delete | Delete non-system roles |
Creating a Role
- Click Create Role (requires
admin-roles:create). - Enter a name (required, max 100 characters) and an optional description.
- Use the permission picker to select which admin permissions the role grants. Permissions come from the backend registry via
/api/admin-permissions, grouped by the category derived from the part of the permission string before the:, each with a tri-state "select all in category" checkbox. - Click Create Role to save.
Editing a Role
Click any row in the table, or the pencil in the Actions column, to open the edit dialog (requires admin-roles:edit).
All fields — name, description, and permissions — are editable for all roles, including system roles. Save Changes stays disabled until something actually changed and sends only the changed fields.
admin:access Permission
Every role automatically includes the admin:access permission. The picker skips it — it cannot be selected or deselected. It is required for any admin user to access the admin panel at all.
System Roles
Roles with is_system: true (shown with a "System" badge) are protected:
- They are editable — you can change their name, description, and permissions.
- They are not deletable — the Delete Role button in the dialog's Danger Zone is disabled, with "System roles cannot be deleted." shown as both a tooltip and a note underneath. The server refuses the delete as well.
The built-in system_admin role is an example of a system role.
Member Management
The edit dialog includes a Members section:
- Lists all admin users currently holding the role with their name, email, and avatar.
- Use the search box to find users by name or email and add them to the role. The search is debounced and excludes users who already hold the role.
- Click the remove button next to any member to unassign them.
API
| Action | GraphQL | REST |
|---|---|---|
| List roles | adminRoles | GET /v1/admin/admin-roles |
| Get a role | adminRole | GET /v1/admin/admin-roles/\{id\} |
| Create a role | adminCreateRole | POST /v1/admin/admin-roles |
| Update a role | adminUpdateRole | PATCH /v1/admin/admin-roles/\{id\} |
| Delete a role | adminDeleteRole | DELETE /v1/admin/admin-roles/\{id\} |
| List role members | adminRoleMembers | GET /v1/admin/admin-roles/\{id\}/members |
| Assign a member | adminAssignUserRole | PUT /v1/admin/admin-roles/\{id\}/members/\{userId\} |
| Unassign a member | adminUnassignUserRole | DELETE /v1/admin/admin-roles/\{id\}/members/\{userId\} |
| Permission registry for the picker | allAdminPermissions | GET /v1/admin/admin-permissions |
Assigning and unassigning members is gated on admin-roles:edit, not on a dedicated permission.
A role's permission list is validated against the backend registry on create and update, so a wildcard such as accounts:* can never be persisted into an admin role.