Roles & Permissions
Role definitions, capability matrix, grant ceiling rules, and the last-owner invariant.
Roles & Permissions
Overview
Every member of an organization holds exactly one of three built-in roles. Roles are bundles of fine-grained capabilities — dot-namespaced resource.verb strings such as service.edit or audit.view. Every UI action and every API endpoint is gated by a capability, never by a role name, so role definitions can evolve without changing endpoint behavior.
| Role | Intended for |
|---|---|
| Owner | Founders and administrators with full control, including billing, SSO, member management, and token oversight |
| Admin | Engineers who manage the monitoring inventory day to day and can invite new members |
| Member | Read-only collaborators who need full visibility but make no changes |
Role × Capability Matrix
| Capability | Member | Admin | Owner |
|---|---|---|---|
| Organization | |||
org.view — view organization profile | ✓ | ✓ | ✓ |
org.edit — change organization settings | — | — | ✓ |
org.delete — delete the organization | — | — | ✓ |
org.billing — manage plan and billing | — | — | ✓ |
org.convert — convert personal workspace to team | — | — | ✓ |
| Members | |||
member.view — list members | ✓ | ✓ | ✓ |
member.invite — invite new members | — | ✓¹ | ✓ |
member.role_edit — change a member's role | — | — | ✓ |
member.remove — remove a member | — | — | ✓ |
| SSO | |||
sso.view — view SSO configuration | — | — | ✓ |
sso.edit — configure SSO and email-routing domains | — | — | ✓ |
| Governance | |||
audit.view — view the organization audit log | — | ✓ | ✓ |
token.inventory_view — view members' org token metadata | — | — | ✓ |
token.revoke — revoke members' org tokens | — | — | ✓ |
| Projects | |||
project.view | ✓ | ✓ | ✓ |
project.create / project.edit / project.delete | — | ✓ | ✓ |
| Services | |||
service.view | ✓ | ✓ | ✓ |
service.create / service.edit / service.delete | — | ✓ | ✓ |
| Integrations | |||
integration.view | ✓ | ✓ | ✓ |
integration.create / integration.edit / integration.delete | — | ✓ | ✓ |
| Alert rules | |||
alert_rule.view | ✓ | ✓ | ✓ |
alert_rule.create / alert_rule.edit / alert_rule.delete | — | ✓ | ✓ |
| Expectations | |||
expectations.view | ✓ | ✓ | ✓ |
expectations.edit | — | ✓ | ✓ |
| Incidents | |||
incident.view | ✓ | ✓ | ✓ |
incident.ack — acknowledge incidents | — | ✓ | ✓ |
¹ Admins may invite Members only — see the grant ceiling below.
Members are strictly read-only
The Member role carries every *.view capability and nothing else — Members can browse the entire monitoring inventory, incident history, and dashboards, but cannot create, edit, delete, or acknowledge anything. Secret values (integration credentials, token values) are never serialized to any role.
Role-Granting Rules (Grant Ceiling)
When inviting a user or changing a member's role, an actor may only grant roles strictly below their own:
- Only an Owner may grant the Owner or Admin role.
- An Admin may invite users as Member only, and cannot change roles at all (
member.role_editis Owner-only). - Violations are rejected with a structured
403error and recorded in the audit log as anauthz.deniedevent.
Last-Owner Invariant
An organization must always have at least one Owner. The following are blocked with 409 Conflict while a user is the sole Owner of any team organization:
- demoting that user to Admin or Member,
- removing that user from the organization,
- the user leaving the organization themselves,
- deleting the user's account.
Promote a second Owner first, then proceed.
Listing Roles via the API
curl https://app.uptimehunt.io/api/v1/orgs/acme/roles \
-H "Authorization: Bearer {access_token}"Returns the built-in roles with their capability lists. Clients that render role pickers should read this endpoint rather than hard-coding role names, so they stay forward-compatible with future custom roles.
Custom roles
Owner-defined custom roles (arbitrary capability sets) are on the roadmap. The permission model is already shaped for them — the matrix above describes the built-in roles.