Reten Docs

Roles & Permissions

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

Reten implements hierarchical Role-Based Access Control (RBAC) with granular permissions grouped by domain. The tables below cover the most common domains; the full permission set is larger and additive.

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 activity setup and dispatch configsSUPER_ADMIN, ADMIN

Activity Generation & Lifecycle Domain

PermissionvalueDescriptionRoles
VIEW_ACTIVITY_GENERATION_CONFIGSactivity-generation-config:viewView AGCs and their lifecycle pillars (incl. per-pillar configHashes)SUPER_ADMIN, ADMIN
CREATE_ACTIVITY_GENERATION_CONFIGactivity-generation-config:createCreate an AGC with its 3 lifecycle pillarsSUPER_ADMIN, ADMIN
UPDATE_ACTIVITY_GENERATION_CONFIGactivity-generation-config:updateUpdate AGC metadata and replace lifecycle pillars in placeSUPER_ADMIN, ADMIN
DELETE_ACTIVITY_GENERATION_CONFIGactivity-generation-config:deleteArchive an AGC (cascades to its lifecycle configs)SUPER_ADMIN, ADMIN
VIEW_LIFECYCLE_CONFIGSlifecycle-config:viewView the read-only lifecycle configs (activation / engagement / resurrection)SUPER_ADMIN, ADMIN
DELETE_LIFECYCLE_CONFIGlifecycle-config:deleteInternal — gates lifecycle archive/restore in the trash cascadeSUPER_ADMIN, ADMIN

Lifecycle configs have no standalone create/edit/delete permissions: a lifecycle config is created and edited only through the AGC flow, gated by CREATE_ACTIVITY_GENERATION_CONFIG / UPDATE_ACTIVITY_GENERATION_CONFIG.

API Key Domain

PermissionDescriptionRoles
MANAGE_API_KEYSCreate, list, and revoke API keysSUPER_ADMIN, ADMIN

Machine-to-machine (M2M) compute access

The retention engine that computes commerce lifecycle states reads AGCs programmatically. It uses an existing API key scoped to the tenant (no new auth mechanism) carrying VIEW_ACTIVITY_GENERATION_CONFIGS (activity-generation-config:view). With that permission it calls GET /api/activity-generation-configs and GET /api/activity-generation-configs/:id to read each pillar and its configHashes (to cheaply detect when a config changed), then writes the computed states back via commerce lifecycle snapshots.

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.