Getting Started
Roles & Permissions
Role hierarchy, permissions, and how they gate API endpoints.
Reten implements hierarchical Role-Based Access Control (RBAC) with 4 roles and 19 granular permissions across 7 domains.
Role Hierarchy
SUPER_ADMIN (highest)
│
▼
ADMIN
│
▼
FDE
│
▼
VIEWER (lowest)Higher roles inherit all permissions of lower roles and can manage users at equal or lower levels.
Roles
| Role | Level | Description |
|---|---|---|
SUPER_ADMIN | Highest | Full system access, can manage all users and tenants |
ADMIN | High | Tenant administration, can manage most resources |
FDE | Medium | Field operations, can create activities and view data |
VIEWER | Lowest | Read-only access to tenant data |
Permissions by Domain
User Domain
| Permission | Description | Roles |
|---|---|---|
CREATE_USER | Create new users | SUPER_ADMIN, ADMIN |
VIEW_USERS | List tenant users | SUPER_ADMIN, ADMIN, FDE |
UPDATE_USER | Update user details and roles | SUPER_ADMIN, ADMIN |
DELETE_USER | Delete users | SUPER_ADMIN |
RESET_USER_PASSWORD | Reset another user's password | SUPER_ADMIN, ADMIN |
Tenant Domain
| Permission | Description | Roles |
|---|---|---|
CREATE_TENANT | Create new tenants | SUPER_ADMIN |
VIEW_TENANTS | List all tenants | SUPER_ADMIN, ADMIN |
UPDATE_TENANT | Update tenant details | SUPER_ADMIN |
DELETE_TENANT | Delete tenants | SUPER_ADMIN |
Commerce Domain
| Permission | Description | Roles |
|---|---|---|
MANAGE_COMMERCES | Full CRUD on commerces, addresses, users, contacts | SUPER_ADMIN, ADMIN, FDE |
SYNC_COMMERCES | Batch sync commerces from external systems | SUPER_ADMIN, ADMIN |
Operator Domain
| Permission | Description | Roles |
|---|---|---|
MANAGE_OPERATORS | Full CRUD on operators | SUPER_ADMIN, ADMIN, FDE |
SYNC_OPERATORS | Batch sync operators from external systems | SUPER_ADMIN, ADMIN |
Route Domain
| Permission | Description | Roles |
|---|---|---|
MANAGE_ROUTES | Full CRUD on routes and operator assignments | SUPER_ADMIN, ADMIN, FDE |
Activity Domain
| Permission | Description | Roles |
|---|---|---|
VIEW_ACTIVITIES | List and view activities, results, configs | SUPER_ADMIN, ADMIN, FDE, VIEWER |
CREATE_ACTIVITY | Create activities and results | SUPER_ADMIN, ADMIN, FDE |
CANCEL_ACTIVITY | Cancel activities | SUPER_ADMIN, ADMIN |
MANAGE_ACTIVITY_CONFIG | Manage resolution configs, attribute policies, dispatch configs | SUPER_ADMIN, ADMIN |
API Key Domain
| Permission | Description | Roles |
|---|---|---|
MANAGE_API_KEYS | Create, list, and revoke API keys | SUPER_ADMIN, ADMIN |
How Permissions Gate Endpoints
For protected routes, guards execute in this order:
- JwtAuthGuard — Validates the JWT access token or API key (global)
- TenantGuard — Validates the user belongs to the requested tenant
- PermissionsGuard — Checks the user has the required permissions
Each endpoint page in the API reference lists the required permission (e.g., Auth: Required — CREATE_ACTIVITY permission).
Role Hierarchy Enforcement
- Users cannot modify roles of users at the same or higher level
- Users cannot reset passwords of users at the same or higher level
- Users cannot assign roles higher than their own
Tenant Context
Most endpoints require a tenant context:
- JWT auth: provide
x-tenant-idheader with the tenant UUID - API key auth: tenant is resolved automatically from the key
The system validates that the authenticated user belongs to the requested tenant before proceeding.