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

# The roles editor

> Create and manage roles from the permission catalog, and understand why the four presets are read-only.

export const PermissionNote = ({perm}) => <Info>
    Requires the <code>{perm}</code> permission. Ask your administrator if an
    action described here is missing from your screen — see
    [Roles & permissions](/help/concepts/roles-and-permissions).
  </Info>;

<PermissionNote perm="role:write" />

**Settings → Roles & permissions.**

A role is a named set of permission keys. Every employee has exactly one.

## Creating a role

<Steps>
  <Step title="Name it">
    Something that describes the job, not the permissions — "Shift Supervisor", not "Can approve leave".
  </Step>

  <Step title="Tick permissions">
    The full catalog, grouped as in [Roles & permissions](/help/concepts/roles-and-permissions): self and profile, people, org structure, roles and access, attendance, leave, payroll, compliance, reports, shifts and rosters, regularization and overtime, documents and devices, integrations, platform.
  </Step>

  <Step title="Save">
    The role is immediately available on the employee wizard's role picker.
  </Step>
</Steps>

## Building a role well

<Warning>
  **Understand `hr:approve` before granting it.** It is not just "the HR approval step". It is the **organization-wide scope override** — a holder can act on every employee in the organization, not just their direct reports. Granting it to a team lead gives them authority over everyone.
</Warning>

<Warning>
  **`role:write` is a self-escalation path.** Its holder can edit *any* role including their own, and there is no self-role special case. Anyone with `role:write` can grant themselves everything. This is exactly why the shipped HR preset does not have it.
</Warning>

<Tip>
  Start from what a preset does and adjust. Copy the Manager set and add `shift:write` for a supervisor who builds rosters; copy Employee and add `team:read` for a lead who needs visibility but no authority.
</Tip>

## The four presets are read-only

Employee, Manager, HR and Admin cannot be edited or deleted. Opening one shows it read-only with no Save button.

This is deliberate rather than a limitation: the presets are the documented baseline, and a silently drifted "Admin" role is a security problem nobody notices. Build a new role instead of editing a preset.

## Deleting a role

A role with employees assigned to it **cannot be deleted**. The row shows how many hold it; reassign them first.

## When changes take effect

Immediately, for everyone holding the role — including you, if you edit your own.

<Note>
  **There is no forced sign-out.** Your own live permissions refresh, so the next screen you open reflects the change, but existing sessions are not bounced. If you are removing access from someone urgently, revoke their sessions as well — see [Sessions and devices](/help/admin/sessions-and-devices).
</Note>

## What the editor does not show

<Note>
  **There is no "who has this role" drill-down.** The row shows a count of holders, which is what blocks deletion, but not the list of people. Use the employee directory, filtered by role, to see who they are.
</Note>