Roles — /rbac/roles
The Roles page lists every role available in your workspace. Use it to browse, search, filter, create, edit, and delete roles. For a tree of role parent/child relationships, see Role Hierarchy.
What you see
A table (cards on mobile) with one row per role:
- Name — the role's display name (e.g. Project Manager)
- Type —
system(built-in, cannot be deleted) orcustom - Permissions — count of distinct permissions this role grants
- Members — number of actors currently assigned this role
- Updated — when the role was last edited
Tap any row to open the Role Detail page.
Filtering and search
- Search box — filter by role name (case-insensitive, partial match)
- Type filter —
All,System,Custom - Tag filter — choose tags to narrow results to roles that carry those tags
The list updates as you type. Filters combine with AND logic — choose Custom + a tag to show only custom roles with that tag.
Things you can do
| Task | How | Permission |
|---|---|---|
| Browse roles | Scroll the list | read access to RBAC |
| Open a role | Tap the row | read access to RBAC |
| Create a role | Tap + New Role in the page header | role:create |
| Edit a role | Tap the pencil icon on a row | role:update |
| Delete a role | Tap the trash icon, confirm in dialog | role:delete |
| Filter by tag | Tap a tag chip in the toolbar | read access to RBAC |
System roles (e.g. Owner, Admin) cannot be deleted. The trash icon is hidden for them.
Creating a role
The + New Role button navigates to a dedicated route (/rbac/roles/create) hosting a step-by-step builder:
- Basics — name, description, optional parent role.
- Permissions — pick the permissions this role grants. Permissions are grouped by resource for easier browsing.
- Review — confirm and save.
Note on parent role. The parent-role field is metadata only — it does not cause permissions to be inherited from the parent. A child role starts with no permissions and only grants what you explicitly select in step 2. Use the parent link to group related roles for display and discovery, not to share permissions. (See
modules/rbac/specs/02-domain-model.mdandmodules/rbac/specs/06-permissions-authz.md.)
Tags. Role tags are surfaced as read-only chips on the role detail page (
RbacTagChips+getEntityTags). Tag attach/detach is handled in the workspace Tags admin surface, not in the role creation flow.
Once saved, the role appears in the list and is immediately available to assign.
Editing a role
Editing a role opens the same builder pre-populated at /rbac/roles/:roleId/edit. Changes apply to everyone who currently has the role — there is no draft state. If you need a sandbox version, clone the role first (use Duplicate from the role's detail page).
Deleting a role
The delete dialog supports two outcomes:
- Delete and reassign — pick a target role; every actor currently assigned the role being deleted is moved to the target role in a single step. Use this when the role has active members and you want to avoid an access gap (the underlying contract is
deleteRole(id, reassignToRoleId); seemodules/rbac/specs/03-graphql-contract.mdandmodules/rbac/specs/05-workflows.md). - Delete without reassignment — the role is removed and the assignment to it is dropped. Members keep whatever other roles they had, but lose anything the deleted role was uniquely granting.
Either way:
- The role is removed from this workspace.
- The action cannot be undone and is logged in the audit feed.
You will be asked to confirm before the deletion runs.
Pagination
The list is paginated. The page footer shows current page and total rows. Choose page size (25 / 50 / 100) from the dropdown.
Empty state
If your workspace has no custom roles yet, you see a friendly empty card with a + Create your first role button. System roles are still visible in the table above the empty state when applicable.
Tips
- Tags are searchable from the same toolbar — combining a tag and a name search is the fastest way to find a role in a large workspace.
- "Members" count is live — it updates as soon as someone gains or loses an assignment.
- If you cannot delete a role you own, check that no system process or integration depends on it. The error toast will tell you the conflict.