Roles and permissions
Grant operators only the Console capabilities they need.
Roles decide which console pages a person can open and which buttons they see. Use Settings → RBAC to review the four system roles and to build custom roles with a narrower set of permissions.
Before you start#
- Opening Settings → RBAC needs
roles:view. Under the built-in roles that is Owner and Admin. - Create Role, Edit role and Delete role need
roles:create,roles:updateandroles:delete. Under the built-in roles only Owner has them. - System roles (Owner, Admin, User, Readonly) cannot be edited or deleted. The control plane rejects both with “cannot modify system roles” and “cannot delete system roles”.
- Roles do not grant access to private services. Use Access policies for that.
Review existing roles#
- Open Settings → RBAC. The page is titled Roles & Permissions.
- Read the table. Type shows System or Custom. Permissions shows the first three grants and a “+N more” chip.
- Choose a role name or View role in the action menu to open its detail page.

Roles & Permissions lists the four system roles and any custom roles, with the first three grants and a +N more chip per row.
A system role opens read-only with the banner “System roles cannot be edited. These roles are managed by PulseHA and provide the default permission levels.” The Permissions section lists grants grouped by resource.
Create a custom role#
- On Roles & Permissions, choose Create Role.
- Under Basic Information, enter a Role Name (required) and a Description. The description must be under 500 characters.
- Optionally pick Inherits From. Only other custom roles in your tenant are offered. The role inherits every permission of its parent.
- Under Permissions, optionally choose a template after Start from: to copy an existing role’s grants. Clear all empties the selection.
- Use Search permissions to filter. Tick individual permissions, or use the checkbox beside a resource heading to select all of its permissions.
- Check the Role Summary panel, then choose Create Role.

Create Role with the permission catalogue grouped by resource. Ticking a resource heading selects all of its permissions and the Role Summary counts them.
You should see “Role created” and the new row marked Custom. Assign it from Settings → Users by editing a user.
Edit or delete a custom role#
- Open the action menu on a custom role and choose Edit role.
- Change the name, description, parent or permissions, then Save Changes.
- To delete, choose Delete role and confirm Delete.
Deletion fails while anyone still holds the role. The error names the count: “role is still assigned to N user(s) or group(s); reassign them before deleting”.
Reference#
System roles and their seeded descriptions:
| Role | Description | Typical reach under the built-in matrix |
|---|---|---|
| Owner | Full administrative access to tenant resources | Everything, including tenant settings, SSO, roles, billing and user removal. |
| Admin | Administrative access with some restrictions | Users, devices, policies, services, gateways, audit. Cannot change tenant settings, SSO or roles. |
| User | Standard user with limited permissions | Views resources and can create devices and policies. Cannot update or delete. |
| Readonly | Read-only access to tenant resources | Views resources only. |
Permissions are named resource.action. The seed includes these groups; the picker shows the full current list:
| Resource | Permissions |
|---|---|
| users | users.read, users.invite, users.update, users.remove |
| devices | devices.read, devices.register, devices.revoke |
| policies | policies.read, policies.create, policies.update, policies.delete |
| gateways | gateways.read, gateways.create, gateways.update, gateways.delete |
| routes | routes.read, routes.create, routes.update, routes.delete |
| sso | sso.read, sso.create, sso.update, sso.delete |
| audit | audit.read |
| tenant | tenant.read, tenant.update |
Form fields:
| Field | Rule |
|---|---|
| Role Name | Required. |
| Description | Under 500 characters. |
| Inherits From | Custom roles in this tenant only. System roles are rejected as parents. Cycles are rejected. |
| Permissions | Any number of grants. The summary shows selected/total per resource. |
Troubleshooting#
- Create Role is missing. You lack
roles:create. Under the built-in roles only Owner has it. - “cannot use a system role as a parent”. Pick a custom role in Inherits From, or leave it as None.
- “circular inheritance detected”. The chosen parent already inherits from this role. Choose a different parent.
- “a role cannot be its own parent”. Pick a different role in Inherits From.
- Delete fails with an assignment count. Reassign those users under Settings → Users, then retry.
- Two operators see different pages. Navigation is permission-gated. Compare their roles on this page rather than sharing accounts.
- “No roles found. System roles should be present.” The roles list failed to load. Refresh. If it persists, raise a support ticket.