Roles & Permissions

Reten implements hierarchical Role-Based Access Control (RBAC) with granular permissions grouped by domain. The tables below list every permission, grouped by the same domains the API uses; a user with several roles holds the permissions of all of them.

Permissions and roles are written as the value the API sends and receives: activity:view, admin. That is the value you send in the permissions of POST /api/api-keys and in the roles of POST /api/auth/register, and the one the API returns in a 403 — Required permissions: activity:view.

Role Hierarchy

super_admin (highest)
    │
    ▼
  admin
    │
    ▼
   fde
    │
    ▼
supervisor
    │
    ▼
 operator
    │
    ▼
  viewer (lowest)

Each role has its own explicit list of permissions: a higher role does not automatically hold every permission of the roles below it (for example, supervisor has activity:force-retry-dispatch and fde does not). The hierarchy governs user management: a user can only manage users whose role is strictly lower than their own.

Roles

Role	Level	Description
`super_admin`	6 (highest)	Full system access, can manage all users and tenants
`admin`	5	Tenant administration, can manage most resources
`fde`	4	Field Development Engineer with standard access: manages projects, commerces, operators, routes, audiences and activities
`supervisor`	3	Oversees field operators: views activities, submits and edits results, and can force a new dispatch of failed activities
`operator`	2	Field operator with access scoped to the activities assigned to them: views them and registers their results; can also manage commerces
`viewer`	1 (lowest)	Read-only access to tenant data

Permissions by Domain

User Domain

Permission	Description	Roles
`user:create`	Create new users	`super_admin`, `admin`
`user:view`	List tenant users	`super_admin`, `admin`, `fde`, `supervisor`, `viewer`
`user:update`	Replace a user's roles (`PUT /api/user/:id/roles`)	`super_admin`, `admin`
`user:delete`	Not required by any endpoint today	`super_admin`, `admin`
`user:reset-password`	Reset another user's password	`super_admin`, `admin`

Tenant Domain

Permission	Description	Roles
`tenant:create`	Create new tenants	`super_admin`
`tenant:view`	List all tenants	`super_admin`, `admin`
`tenant:update`	Update tenant details	`super_admin`
`tenant:delete`	Not required by any endpoint today	`super_admin`

Project Domain

Permission	Description	Roles
`project:create`	Create projects together with their root audience (`POST /api/projects`)	`super_admin`, `admin`, `fde`
`project:view`	List the tenant's projects (`GET /api/projects`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`project:update`	Rename projects (`PATCH /api/projects/:id`) and edit their root audience	`super_admin`, `admin`, `fde`

Commerce Domain

Permission	Description	Roles
`commerce:manage`	Full CRUD on commerces, addresses, users, contacts (deleting a commerce requires `commerce:delete`)	`super_admin`, `admin`, `fde`, `operator`
`commerce:batch-upsert`	Batch upsert commerces from external systems (`POST /api/integration/commerces/batch-upsert`)	`super_admin`, `admin`

Commerce Lifecycle Snapshot Domain

Permission	Description	Roles
`commerce-lifecycle-snapshot:view`	List and look up commerce lifecycle states, including the batch lookup	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`commerce-lifecycle-snapshot:create`	Write commerce lifecycle states: single upsert and batch upsert	`super_admin`, `admin`, `fde`, `supervisor`
`commerce-lifecycle-snapshot:sync`	Not required by any endpoint today (the batch upsert requires `commerce-lifecycle-snapshot:create`)	`super_admin`, `admin`, `fde`

Operator Domain

Permission	Description	Roles
`operator:manage`	Full CRUD on operators (deleting an operator requires `operator:delete`)	`super_admin`, `admin`, `fde`
`operator:batch-upsert`	Batch upsert operators from external systems (`POST /api/integration/operators/batch-upsert`)	`super_admin`, `admin`

Route Domain

Permission	Description	Roles
`route:manage`	Full CRUD on routes and operator assignments (deleting a route requires `route:delete`)	`super_admin`, `admin`, `fde`
`route:batch-upsert`	Batch upsert routes from external systems (`POST /api/integration/routes/batch-upsert`)	`super_admin`, `admin`

Activity Domain

Permission	Description	Roles
`activity:view`	List and view activities, results, configs	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`activity:create`	Create activities (`POST /api/activities` and `POST /api/activities/bulk`)	`super_admin`, `admin`, `fde`
`activity:cancel`	Cancel activities	`super_admin`, `admin`, `fde`
`activity:dispatch`	Manually dispatch task activities	`super_admin`, `admin`
`activity:force-retry-dispatch`	Force a new dispatch of a `FAILED` activity (`PATCH /api/activities/:id/force-retry-dispatch`)	`super_admin`, `admin`, `supervisor`
`activity-config:manage`	Manage activity setup and dispatch configs	`super_admin`, `admin`

Audience Criteria Domain

Permission	Description	Roles
`audience-criteria:create`	Create audiences (`POST /api/audience-criterias`)	`super_admin`, `admin`, `fde`
`audience-criteria:view`	List and view audiences, and browse their catalog (`tables`, `tables/:tableName/columns`)	`super_admin`, `admin`, `fde`
`audience-criteria:update`	Update audiences (`PATCH /api/audience-criterias/:id`); editing the root audience also requires `project:update`	`super_admin`, `admin`, `fde`
`audience-criteria:delete`	Delete audiences (`DELETE /api/audience-criterias/:id`)	`super_admin`, `admin`, `fde`
`audience-criteria:view-sql`	Generate, validate and preview the SQL of an audience	`super_admin`, `admin`, `fde`

Event Criteria Domain

Permission	Description	Roles
`event-criteria:create`	Create event filters (`POST /api/event-criterias`)	`super_admin`, `admin`, `fde`
`event-criteria:view`	List and view event filters, and browse their catalog (`tables`, `tables/:tableName/columns`)	`super_admin`, `admin`, `fde`
`event-criteria:update`	Update event filters (`PATCH /api/event-criterias/:id`)	`super_admin`, `admin`, `fde`
`event-criteria:delete`	Delete event filters (`DELETE /api/event-criterias/:id`)	`super_admin`, `admin`, `fde`
`event-criteria:view-sql`	Generate, validate and preview the SQL of an event filter	`super_admin`, `admin`, `fde`

Activity Generation & Lifecycle Domain

Permission	Description	Roles
`activity-generation-config:view`	View AGCs and their lifecycle pillars (incl. per-pillar `configHashes`)	`super_admin`, `admin`
`activity-generation-config:create`	Create an AGC with its 3 lifecycle pillars	`super_admin`, `admin`
`activity-generation-config:update`	Update AGC metadata, replace lifecycle pillars in place, publish and pause	`super_admin`, `admin`
`activity-generation-config:delete`	Archive an AGC (cascades to its lifecycle configs)	`super_admin`, `admin`
`lifecycle-config:view`	View the read-only lifecycle configs (activation / engagement / resurrection)	`super_admin`, `admin`
`lifecycle-config:delete`	Internal — gates lifecycle archive/restore in the trash cascade	`super_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 activity-generation-config:create / activity-generation-config:update.

Dispatch Provider Domain

Permission	Description	Roles
`dispatch-provider:manage`	Edit the channel definitions of a dispatch provider: recommended payload mapping and settings, and whether a mapping is required (`PATCH /api/dispatch-providers/:providerId/channel-definitions/:definitionId`)	`super_admin`

Data Query Domain

Permission	Description	Roles
`data-query:view`	Read the data catalog metadata: tables and their columns (`GET /api/data-query/tables`, `GET /api/data-query/tables/:tableName/columns`)	`super_admin`, `admin`, `fde`

API Key Domain

Permission	Description	Roles
`api-key:manage`	Create, list, revoke, and edit the permissions of API keys	`super_admin`, `admin`

Activity Result Domain

Permission	Description	Roles
`activity-result:submit`	Submit activity results (`POST /api/activity-results/tasks` and `POST /api/integration/activity-results/tasks`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`
`activity-result:edit`	Edit activity results (`PATCH /api/activity-results/tasks/:id`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`
`activity-result:sync-stream`	Read the incremental sync stream of task results (`GET /api/activity-results/tasks/sync`)	`super_admin`, `admin`

Trash & Deletion Domain

Permission	Description	Roles
`trash:view`	View archived records in the trash and restore them (`/api/trash`). Viewing a record's detail or cascade preview and restoring it also require the permission that deletes that kind of record (for example, `commerce:delete`). Permanently deleting a record from the trash is limited to `super_admin`	`super_admin`, `admin`, `fde`
`trash:manage-settings`	View and change the tenant's trash retention settings (`GET` and `PATCH /api/trash/settings`)	`super_admin`, `admin`
`commerce:delete`	Delete commerces, which moves them to the trash (`DELETE /api/commerces/:id`)	`super_admin`, `admin`, `fde`
`operator:delete`	Delete operators, which moves them to the trash (`DELETE /api/operators/:id`)	`super_admin`, `admin`, `fde`
`route:delete`	Delete routes, which moves them to the trash (`DELETE /api/routes/:id`)	`super_admin`, `admin`, `fde`
`supervisor:delete`	Delete supervisors, which moves them to the trash (`DELETE /api/supervisors/:id`)	`super_admin`, `admin`, `fde`

Machine-to-machine (M2M) compute access

The retention engine that computes commerce lifecycle states reads AGCs programmatically. It uses an API key (no new auth mechanism) carrying 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. Both AGC endpoints are project-scoped: with a tenant key, every call sends x-project-id (without it the API responds 400 — Falta el header obligatorio x-project-id.), and a project key only reads the AGCs of its own project — see Key scope.

How Permissions Gate Endpoints

For protected routes, the API checks each request in this order:

Authentication — The JWT access token or API key is valid (every protected route)
Tenant — The user belongs to the requested tenant
Project — On project-scoped endpoints, the active project is valid (see Authentication → Project Context)
Permissions — The user has the required permissions

Each endpoint page in the API reference lists the required permission (e.g., Auth: Required — activity:create 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 a role equal to or higher than their own

In all three cases the API responds 403.

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.

Project-scoped endpoints also need the project (see Authentication → Project Context):

JWT auth and tenant keys: provide the x-project-id header with the project UUID. On project-optional endpoints the header is optional and narrows the request to that project
Project keys: the key always works in its own project, so the header is not needed (see Key scope)