> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Role Management

> Create and manage custom permission roles; edit role names, permission matrices, and user assignments; review system-provided default roles.

Role management page at `/settings/roles` where organization administrators create and manage custom roles and review system roles.

## Overview

The Roles page displays two tabs — **Custom Roles** and **System Roles** — loaded via `useCustomRoles`. Custom roles are organization-specific and can be created, edited, and deleted; system roles are platform-provided and read-only. The page guards against missing user or organization context with an error message. Navigation to create a new role goes to `/settings/roles/new`; editing an existing role goes to `/settings/roles/:id`.

## Who it's for

Access follows your organization's role and module configuration. The component requires a valid authenticated user and an active organization context. Creating new roles requires `pf.users.manage`.

## Before you start

* You must be signed in with a valid organization context.
* Understand your organization's access model before creating or modifying roles.

## Steps

1. Navigate to `/settings/roles`.
2. On the **Custom Roles** tab, review existing custom roles for your organization.
3. To create a new role, navigate to `/settings/roles/new`.
4. To edit a role, click its row to navigate to `/settings/roles/:id`.
5. Review the **System Roles** tab to see platform-provided roles.

## Key concepts

**Custom role** — A role created by your organization with a specific set of permissions. Scoped to the organization.

**System role** — A platform-provided role that cannot be modified. SME: confirm the full list of system roles.

## Creating a role

Administrators can create a new custom role at `/settings/roles/new`. This route renders `CreateRolePage` with no additional permission wrapper on the route itself.

The New Role page presents a `RoleForm` for defining a custom role. The form collects a role name, optional description, and permission assignments. The `useCreateRole()` mutation (from `useCustomRoles`) persists the new role scoped to the current organization. The page guards against missing user or organization context and redirects to `/settings/roles` on successful creation or if context is unavailable.

1. Navigate to **Settings > Roles** and select **New Role**, or go directly to `/settings/roles/new`.
2. Enter a **Name** for the role.
3. Add an optional **Description**.
4. Assign permissions using the role form.
5. Save the role.

## Editing a role

The Edit Role page (`/settings/roles/:id`) provides a full editor for a custom role, allowing administrators to modify its name and description, configure its permission matrix, and manage which users are assigned to the role.

The page loads the role via `useCustomRole(roleId)` and fetches current assignees via `useRoleAssignees`. Updates are submitted through `useUpdateRole`. The form uses `RoleForm` for name and description fields, and a `PermissionAssignmentMatrix` for configuring which permissions are granted to the role. A second **Assignees** tab shows users currently assigned to the role. A `RoleAssignmentDialog` allows adding new assignees. The back button navigates to `/settings/roles`.

Understand the permission matrix structure before making changes that may affect multiple users.

<Steps>
  <Step title="Open role editor">
    Navigate to `/settings/roles/:id`. The form loads with the role's current name, description, and permissions.
  </Step>

  <Step title="Edit role name and description">
    Use the `RoleForm` fields to update the role's display name and description.
  </Step>

  <Step title="Configure permissions">
    Use `PermissionAssignmentMatrix` to grant or revoke individual permissions for the role. The matrix displays all available platform permissions grouped by module.
  </Step>

  <Step title="Manage assignees">
    Switch to the **Assignees** tab to view current users assigned to this role. Click **Assign Users** to open `RoleAssignmentDialog`. Adding or removing assignees does not affect the role's permission configuration.
  </Step>

  <Step title="Save changes">
    Submit the form. Changes are applied via `useUpdateRole`.
  </Step>
</Steps>

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/roles/pages/RolesPage.tsx
  * src/platform/permissions/hooks/useCustomRoles.ts
  * src/platform/roles/components/RoleList.tsx
  * src/platform/roles/pages/CreateRolePage.tsx
  * src/platform/roles/pages/EditRolePage.tsx
  * src/platform/permissions/hooks/useRoleAssignments.ts
</Accordion>