Reten Docs

Roles & Permissions

Role hierarchy, permissions, and how they gate API endpoints.

Reten implements hierarchical Role-Based Access Control (RBAC) with 4 roles and 20 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

RoleLevelDescription
SUPER_ADMINHighestFull system access, can manage all users and tenants
ADMINHighTenant administration, can manage most resources
FDEMediumField operations, can create activities and view data
VIEWERLowestRead-only access to tenant data

Permissions by Domain

User Domain

PermissionDescriptionRoles
CREATE_USERCreate new usersSUPER_ADMIN, ADMIN
VIEW_USERSList tenant usersSUPER_ADMIN, ADMIN, FDE
UPDATE_USERUpdate user details and rolesSUPER_ADMIN, ADMIN
DELETE_USERDelete usersSUPER_ADMIN
RESET_USER_PASSWORDReset another user's passwordSUPER_ADMIN, ADMIN

Tenant Domain

PermissionDescriptionRoles
CREATE_TENANTCreate new tenantsSUPER_ADMIN
VIEW_TENANTSList all tenantsSUPER_ADMIN, ADMIN
UPDATE_TENANTUpdate tenant detailsSUPER_ADMIN
DELETE_TENANTDelete tenantsSUPER_ADMIN

Commerce Domain

PermissionDescriptionRoles
MANAGE_COMMERCESFull CRUD on commerces, addresses, users, contactsSUPER_ADMIN, ADMIN, FDE
SYNC_COMMERCESBatch sync commerces from external systemsSUPER_ADMIN, ADMIN

Operator Domain

PermissionDescriptionRoles
MANAGE_OPERATORSFull CRUD on operatorsSUPER_ADMIN, ADMIN, FDE
SYNC_OPERATORSBatch sync operators from external systemsSUPER_ADMIN, ADMIN

Route Domain

PermissionDescriptionRoles
MANAGE_ROUTESFull CRUD on routes and operator assignmentsSUPER_ADMIN, ADMIN, FDE

Activity Domain

PermissionDescriptionRoles
VIEW_ACTIVITIESList and view activities, results, configsSUPER_ADMIN, ADMIN, FDE, VIEWER
CREATE_ACTIVITYCreate activities and resultsSUPER_ADMIN, ADMIN, FDE
CANCEL_ACTIVITYCancel activitiesSUPER_ADMIN, ADMIN
DISPATCH_ACTIVITYManually dispatch task activitiesSUPER_ADMIN, ADMIN
MANAGE_ACTIVITY_CONFIGManage resolution configs, attribute policies, dispatch configsSUPER_ADMIN, ADMIN

API Key Domain

PermissionDescriptionRoles
MANAGE_API_KEYSCreate, list, and revoke API keysSUPER_ADMIN, ADMIN

How Permissions Gate Endpoints

For protected routes, guards execute in this order:

  1. JwtAuthGuard — Validates the JWT access token or API key (global)
  2. TenantGuard — Validates the user belongs to the requested tenant
  3. 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-id header 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.