API & Auth
RBAC & Custom Roles
Six system roles, twelve permission keys, and organization-scoped custom roles.
MonSPHERE's access control is permission-based, not just role-name-based — every role, system or custom, is a composition of real permission keys.
The permission catalog
org:manage, org:billing, workspaces:manage, users:manage, apikeys:manage, audit:read, monitors:manage, alerts:manage, agents:manage, dashboards:manage, reports:manage, integrations:manage — 12 keys, fetchable via GET /api/v1/permissions.
System roles
| Role | Typical use |
|---|---|
| Owner | Full control, including billing and org deletion |
| Admin | Full operational control, no billing |
| Operator | Day-to-day monitoring and alert operations |
| Developer | API keys, integrations, dashboards |
| Member | Standard contributor access |
| Viewer | Read-only |
Platform Admin is separate from all of the above — it's a per-user flag (isPlatformAdmin), not an organization role, since it's cross-organization by nature. See Platform Administration.
Custom roles
Organizations can compose their own roles from the same 12 permission keys:
curl -X POST https://api.monsphere.com/api/v1/organizations/:orgId/roles \
-H "X-Api-Key: msk_live_..." \
-d '{"name": "On-Call Lead", "permissions": ["monitors:manage", "alerts:manage", "audit:read"]}'Custom role names are unique per organization (system role names are globally unique) — enforced at the database level, not just in application code.