# Roles and permissions

Access in EvoHub is decided by organization roles. A role is a named set of permissions, and you give roles to people or to teams. This page explains the default roles, how to build your own, and the full list of permissions per product.

## How access works

- Every permission check is made by EvoHub's servers, not only by the console. Hiding a button is a convenience; the API refuses the same action.
- A refused action returns **403 Forbidden**. You stay signed in; you are simply not allowed to do that. See [Errors](https://docs-dev.evohub.io/errors.md).
- What a person can do is the sum of every role they hold, directly or through their teams.
- Roles belong to the organization. The same person can be an Admin in one organization and a Viewer in another.
- Docs sites and changelogs have no roles of their own. Access to them comes from organization roles like everything else.

## Owner and the default roles

Every organization starts with three default roles. They are marked **(default)** in role pickers.

| Role | What it is for |
| --- | --- |
| **Owner** | The person who created the organization. Passes every check, and is the only one who can delete the organization. |
| **Admin** | Runs the organization. A person who holds Admin passes every check, except deleting the organization. |
| **Member** | The day-to-day work across every product: respond to alerts, manage schedules and monitors, run status pages, retros, boards, docs and changelogs. Reads everything else. |
| **Viewer** | Read-only across every product. Sees everything, changes nothing. |

What the default roles allow, product by product:

| | Viewer | Member | Admin |
| --- | --- | --- | --- |
| Read everything (including billing usage and statements, and audit logs) | Yes | Yes | Yes |
| Respond to alerts, edit schedules, escalation policies, maintenance, postmortems | — | Yes | Yes |
| Manage On-Call integrations and voice and update templates | — | Yes | Yes |
| Create and edit monitors, silences and notification channels | — | Yes | Yes |
| Create and edit status pages, components, incidents, maintenance and subscribers | — | Yes | Yes |
| Create and run retros, boards, docs sites and changelogs; write, publish and approve | — | Yes | Yes |
| Invite people and manage teams | — | Yes | Yes |
| Edit or remove members | — | — | Yes |
| Delete a retro, archive a board, delete a docs site or a changelog | — | — | Yes |
| Change org settings, roles, organization keys, login policies, billing (cards, credit, commitment) | — | — | Yes |

> [!NOTE]
> Deleting whole things that a team works in, such as a board, a retro, a docs site or a changelog, is Admin-only by default. Members can create, rename and configure them, but not make them disappear. You can hand this permission to someone deliberately with a custom role.

Administrators can change what the Member and Viewer roles (and the Admin role) grant; everyone holding the role gets the change. Default roles cannot be renamed or deleted.

> [!INFO]
> When the Admin role is given to a **team** rather than to a person, it grants its listed permissions: everything a Member can do plus managing people and the delete permissions above. It does not grant editing roles or issuing organization keys. Only a person whose own role is Admin passes every check.

## Custom roles

Build a custom role when the default roles are too broad or too narrow, for example "Can respond to alerts but not edit schedules" or "Billing only".

:::steps
### Open Roles
Go to **Organization → Roles** and select **Create Role**.

### Name and describe it
Enter a **Name** and a **Description** that says what the role is for.

### Choose permissions
Start from a ready-made level per product (see below), or under **Or start from a default role** pick Admin, Member or Viewer to copy its permissions, then adjust individual boxes. Use the search box to find a permission, or **Everything** to select all you are allowed to grant.

### Save and assign
Save the role. Then give it to people (open a member in **Organization → Members** and add the role) or to a team (open the team in **Organization → Teams** and give it the role).
:::

Rules that apply to every role:

- **You can only grant what you hold.** Permissions you do not hold yourself are greyed out, and the server refuses a role that would give someone more than you have. Only an administrator can give someone the Admin role.
- **A write brings its read.** Selecting a write permission also selects the read it needs, so a role never ends up able to edit something it cannot open.
- **Creating and editing roles** needs the **Roles → Write** permission. Owners and Admins have it; you can give it to others with a custom role.

### Ready-made roles

The role editor offers ready-made levels for each product. Clicking one fills in its permissions; every box stays editable afterwards.

| Product | Levels |
| --- | --- |
| On-Call | **Stakeholder** (sees incidents and maintenance), **Observer** (sees everything, touches nothing), **Responder** (adds acknowledging and resolving), **Manager** (everything, including integrations, settings and the audit log) |
| Uptime | **Viewer**, **Operator** (adds editing and silencing monitors), **Manager** (adds notification channels and the audit log) |
| Status pages | **Viewer**, **Incident Manager** (posts incidents and maintenance, sets component status), **Page Manager** (everything, including domains, design and subscribers) |
| Board | **Uses boards**, **Creates boards** (adds creating boards, settings, visibility and the review gate), **Manages boards** (adds archiving) |
| Docs | **Docs writer** (drafts and change requests), **Docs reviewer** (approves and publishes), **Manages docs sites** (adds site settings, domain and deleting sites) |
| Changelog | **Changelog writer**, **Changelog reviewer**, **Manages changelogs** |
| Retro | **Takes part in retros**, **Runs retros** (adds creating, shaping and sharing retros), **Manages retros** (adds deleting) |
| Organization | **Directory Viewer**, **Inviter**, **Organization Manager** (members, teams, roles, org settings, organization keys, audit log) |
| Billing | **Billing Admin** (usage, statements, payment methods, billing profile, credit and commitment) |

## Permissions reference

Permissions are grouped by product, as in the role editor. Each has an identifier, which you also see on API keys.

| Product | Resource | Permissions |
| --- | --- | --- |
| Organization | Members | `identity:user:read`, `identity:user:write`, `identity:user:invite` |
| | Teams | `identity:team:read`, `identity:team:write` |
| | Roles | `identity:role:read`, `identity:role:write` |
| | Organization Settings | `identity:org:write` |
| | Organization Keys | `identity:apikey:read`, `identity:apikey:write` |
| | Audit Log | `identity:audit:read` |
| On-Call | Alerts | `oncall:alert:read`, `oncall:alert:write`, `oncall:alert:respond` (acknowledge, resolve, snooze, take over, assign) |
| | Incidents | `oncall:incident:read`, `oncall:incident:write` |
| | Schedules | `oncall:schedule:read`, `oncall:schedule:write` |
| | Escalation Policies | `oncall:escalation:read`, `oncall:escalation:write` |
| | Integrations | `oncall:integration:read`, `oncall:integration:write` |
| | Maintenance Windows | `oncall:maintenance:read`, `oncall:maintenance:write` |
| | Postmortems | `oncall:postmortem:read`, `oncall:postmortem:write` |
| | Voice & templates | `oncall:settings:write` |
| | Audit Log | `oncall:audit:read` |
| Uptime | Monitors | `uptime:monitor:read`, `uptime:monitor:write` |
| | Incidents | `uptime:incident:read` |
| | Silences | `uptime:silence:read`, `uptime:silence:write` |
| | Notification Channels | `uptime:channel:read`, `uptime:channel:write` |
| | Audit Log | `uptime:audit:read` |
| Status pages | Pages | `status:page:read`, `status:page:write` |
| | Components | `status:component:read`, `status:component:write` |
| | Incidents | `status:incident:read`, `status:incident:write` |
| | Maintenance | `status:maintenance:read`, `status:maintenance:write` |
| | Subscribers | `status:subscriber:read`, `status:subscriber:write` |
| | Audit Log | `status:audit:read` |
| Retro | Boards | `retro:board:read`, `retro:board:write`, `retro:board:delete` |
| | Cards | `retro:card:read`, `retro:card:write` |
| | Action Items | `retro:action:read`, `retro:action:write` |
| | Audit Log | `retro:audit:read` |
| Board | Boards | `board:board:read`, `board:board:write`, `board:board:delete` (archive) |
| | Lists | `board:list:read`, `board:list:write` |
| | Cards | `board:card:read`, `board:card:write` |
| | Board Members | `board:member:write` |
| | Review Gate | `board:review:write` |
| Docs | Sites | `docs:site:read`, `docs:site:write`, `docs:site:delete` |
| | Pages | `docs:page:write`, `docs:page:publish` (publish and approve) |
| Changelog | Sites | `changelog:site:read`, `changelog:site:write`, `changelog:site:delete` |
| | Entries | `changelog:entry:write`, `changelog:entry:publish` (publish and approve) |
| Billing | Usage | `billing:usage:read` |
| | Statements | `billing:invoice:read` |
| | Payment Methods | `billing:payment:read`, `billing:payment:write` |
| | Billing Profile | `billing:profile:read`, `billing:profile:write` |
| | Credit | `billing:credit:write` |
| | Commitment | `billing:commitment:write` |
| Support | Audit Log | `support:audit:read` |

A few things need no permission at all: every member can see who else is in the organization, see the teams they belong to, open support tickets, and manage their own profile, notifications, sessions, two-factor authentication and personal API keys.

## Related

- [Organizations and teams](https://docs-dev.evohub.io/organizations-and-teams.md)
- [API keys and scopes](https://docs-dev.evohub.io/api-keys-and-scopes.md)
- [Errors](https://docs-dev.evohub.io/errors.md)