Skip to main content

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) or custom
  • 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.

  • 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​

TaskHowPermission
Browse rolesScroll the listread access to RBAC
Open a roleTap the rowread access to RBAC
Create a roleTap + New Role in the page headerrole:create
Edit a roleTap the pencil icon on a rowrole:update
Delete a roleTap the trash icon, confirm in dialogrole:delete
Filter by tagTap a tag chip in the toolbarread 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:

  1. Basics — name, description, optional parent role.
  2. Permissions — pick the permissions this role grants. Permissions are grouped by resource for easier browsing.
  3. 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.md and modules/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); see modules/rbac/specs/03-graphql-contract.md and modules/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.