> ## 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.
# Roles & permissions
> The four role presets, the full permission catalog, and the scope rules that decide whose records you can act on.
Access in OnTime is decided by two separate questions, asked in order:
1. **Can you do this kind of thing at all?** — a *permission key* such as `leave:approve`.
2. **Can you do it to *this person*?** — a *scope* check: yourself, your direct reports, or anyone in the organization.
Holding `leave:approve` does not let you approve everybody's leave. It lets you approve leave, for the people in your scope. Both questions must pass.
## The four presets
OnTime ships with four roles. They are ordinary roles built from the same permission catalog as any role you create — but they are **read-only**, so the baseline can't drift.
11 permissions. Own profile, own punches, own leave, own pay, raise regularizations and overtime requests. Sees nobody else.
22 permissions. Everything an Employee has, plus their team's attendance, and approval rights over leave, regularizations and overtime — **for direct reports only**.
25 permissions. Organization-wide people, leave and payroll authority, compliance and reports, and the `hr:approve` key that clears the direct-manager restriction. Notably **not** the roles editor.
All 53 permissions. Organization configuration, roles, devices, integrations, API keys and the audit log, on top of everything above.
**HR deliberately cannot edit roles.** `role:write` lets its holder edit *any* role, including their own — so granting it to HR would be a path to full Admin. Role administration belongs to Admin.
## Scope: whose records
Permission keys grant capability. Scope decides whose records that capability reaches, and there are exactly three levels.
Acting on yourself. Enabled per surface: you can read your own file and file your own requests, but **you can never approve your own request**, however senior you are.
The people whose manager is you. Not their reports in turn — direct links only.
This is what a manager's approvals queue contains, and it is always overridable by a holder of `hr:approve`.
No narrowing at all. This is what `hr:approve` grants, and it is what administrative keys like `attendance:write` or `audit:read` imply. It is always a deliberate choice, never an accident of the org chart.
Skip-level authority is **not** automatic. A manager two levels above someone is not in their scope; that case is handled by `hr:approve`, granted to HR and Admin. This is intentional — a transitive walk down the org chart would silently widen everyone's authority every time someone is re-parented.
Lists follow the same rule as the pages they link to. A manager's approvals queue shows exactly the requests they can open — you will not see a row and then be refused when you tap it.
## The permission catalog
53 keys, grouped as they appear in the roles editor. ✅ means the preset includes the key.
### Self & profile
| Permission key | What it allows | Employee | Manager | HR | Admin |
| -------------- | ---------------- | :------: | :-----: | :-: | :---: |
| `self:read` | View own profile | ✅ | ✅ | ✅ | ✅ |
| `self:write` | Edit own profile | ✅ | ✅ | ✅ | ✅ |
### People
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ---------------- | ----------------------- | :------: | :-----: | :-: | :---: |
| `employee:read` | View employees | — | ✅ | ✅ | ✅ |
| `employee:write` | Create & edit employees | — | — | — | ✅ |
| `team:read` | View own team | — | ✅ | — | ✅ |
### Org structure
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ------------------ | ------------------ | :------: | :-----: | :-: | :---: |
| `location:read` | View locations | — | — | — | ✅ |
| `location:write` | Manage locations | — | — | — | ✅ |
| `department:read` | View departments | — | — | — | ✅ |
| `department:write` | Manage departments | — | — | — | ✅ |
### Roles & access
| Permission key | What it allows | Employee | Manager | HR | Admin |
| -------------- | -------------------------- | :------: | :-----: | :-: | :---: |
| `role:read` | View roles | — | — | — | ✅ |
| `role:write` | Manage roles & permissions | — | — | — | ✅ |
### Attendance
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ------------------ | -------------------------- | :------: | :-----: | :-: | :---: |
| `attendance:read` | View attendance | — | — | — | ✅ |
| `attendance:punch` | Punch in / out | ✅ | ✅ | ✅ | ✅ |
| `attendance:write` | Edit & override attendance | — | — | — | ✅ |
### Leave
| Permission key | What it allows | Employee | Manager | HR | Admin |
| --------------- | ------------------------------- | :------: | :-----: | :-: | :---: |
| `leave:read` | View leave | ✅ | ✅ | ✅ | ✅ |
| `leave:write` | Apply / manage leave | ✅ | ✅ | ✅ | ✅ |
| `leave:approve` | Approve leave | — | ✅ | ✅ | ✅ |
| `leave:config` | Configure leave types & accrual | — | — | ✅ | ✅ |
### Payroll & pay
| Permission key | What it allows | Employee | Manager | HR | Admin |
| --------------- | -------------- | :------: | :-----: | :-: | :---: |
| `pay:read` | View own pay | ✅ | ✅ | ✅ | ✅ |
| `payroll:read` | View payroll | — | — | ✅ | ✅ |
| `payroll:write` | Run payroll | — | — | ✅ | ✅ |
### Compliance
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ------------------ | ------------------------ | :------: | :-----: | :-: | :---: |
| `compliance:read` | View compliance | — | — | ✅ | ✅ |
| `compliance:write` | File & manage compliance | — | — | ✅ | ✅ |
### Reports
| Permission key | What it allows | Employee | Manager | HR | Admin |
| -------------- | ----------------------- | :------: | :-----: | :-: | :---: |
| `report:read` | View reports | — | — | ✅ | ✅ |
| `report:write` | Create & manage reports | — | — | ✅ | ✅ |
### Shifts & rosters
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ---------------- | ---------------------- | :------: | :-----: | :-: | :---: |
| `shift:read` | View shift templates | — | ✅ | — | ✅ |
| `shift:write` | Manage shift templates | — | — | — | ✅ |
| `roster:read` | View rosters | — | ✅ | — | ✅ |
| `roster:write` | Edit rosters | — | ✅ | — | ✅ |
| `roster:publish` | Publish rosters | — | — | — | ✅ |
| `holiday:read` | View holidays | — | ✅ | — | ✅ |
| `holiday:write` | Manage holidays | — | — | — | ✅ |
| `swap:read` | View swaps | — | ✅ | ✅ | ✅ |
| `swap:write` | Request swaps | — | ✅ | — | ✅ |
| `swap:approve` | Approve swaps | — | — | ✅ | ✅ |
### Regularization & overtime
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ------------------------ | ----------------------- | :------: | :-----: | :-: | :---: |
| `regularization:read` | View regularizations | ✅ | ✅ | ✅ | ✅ |
| `regularization:write` | Raise regularizations | ✅ | ✅ | ✅ | ✅ |
| `regularization:approve` | Approve regularizations | — | ✅ | ✅ | ✅ |
| `overtime:request` | Request overtime | ✅ | ✅ | ✅ | ✅ |
| `overtime:approve` | Approve overtime | — | ✅ | — | ✅ |
### Documents & devices
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ---------------- | ---------------- | :------: | :-----: | :-: | :---: |
| `document:read` | View documents | — | — | — | ✅ |
| `document:write` | Manage documents | — | — | — | ✅ |
| `device:read` | View devices | — | — | — | ✅ |
| `device:write` | Manage devices | — | — | — | ✅ |
### Integrations
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ------------------- | ------------------- | :------: | :-----: | :-: | :---: |
| `integration:read` | View integrations | — | — | — | ✅ |
| `integration:write` | Manage integrations | — | — | — | ✅ |
### Platform
| Permission key | What it allows | Employee | Manager | HR | Admin |
| ------------------- | ----------------------------------------- | :------: | :-----: | :-: | :---: |
| `settings:read` | View organization settings | — | — | ✅ | ✅ |
| `settings:write` | Manage organization settings | — | — | — | ✅ |
| `audit:read` | View audit log | — | — | — | ✅ |
| `notification:read` | View notifications | ✅ | ✅ | ✅ | ✅ |
| `message:write` | Send messages | ✅ | ✅ | ✅ | ✅ |
| `hr:approve` | HR second-step approvals & org-wide scope | — | — | ✅ | ✅ |
| `api:manage` | Manage API keys & webhooks | — | — | — | ✅ |
## Reading the matrix
A few patterns worth noticing:
* **Managers see their team; HR sees the organization.** Manager holds `team:read` and the approve keys but not `hr:approve`, so its authority stops at direct reports. HR holds `hr:approve` and therefore reaches everyone, but holds neither `team:read` nor the org-structure keys.
* **Overtime approval is a manager job, not an HR one.** `overtime:approve` sits with Manager and Admin. HR approves leave and regularizations, not overtime.
* **Swaps split the other way.** Managers *request* swaps (`swap:write`); HR *approves* them (`swap:approve`).
* **Everyone can punch.** `attendance:punch` is in all four presets — administrators are employees too. `attendance:read` (seeing everyone else's) is Admin-only.
## Building your own roles
An administrator can create additional roles from the same checklist. Two rules apply:
* **The four presets cannot be edited or deleted.** Opening one shows it read-only.
* **A role in use cannot be deleted.** Reassign its holders first.
Editing a role takes effect immediately for everyone holding it — including you, if you edit your own. There is no forced sign-out; the next screen you open reflects the change.