Roles y Permisos

Reten implementa Control de Acceso Basado en Roles (RBAC) jerárquico con permisos granulares agrupados por dominio. Las tablas siguientes listan todos los permisos, agrupados por los mismos dominios que usa la API; un usuario con varios roles tiene los permisos de todos ellos.

Los permisos y los roles se escriben con el valor que la API envía y recibe: activity:view, admin. Ese es el valor que envías en permissions de POST /api/api-keys y en roles de POST /api/auth/register, y el que la API devuelve en un 403 — Required permissions: activity:view.

Jerarquía de Roles

super_admin (máximo)
    │
    ▼
  admin
    │
    ▼
   fde
    │
    ▼
supervisor
    │
    ▼
 operator
    │
    ▼
  viewer (mínimo)

Cada rol tiene su propia lista explícita de permisos: un rol superior no tiene automáticamente todos los permisos de los roles inferiores (por ejemplo, supervisor tiene activity:force-retry-dispatch y fde no). La jerarquía rige la gestión de usuarios: un usuario solo puede gestionar usuarios cuyo rol sea estrictamente inferior al propio.

Roles

Rol	Nivel	Descripción
`super_admin`	6 (máximo)	Acceso total al sistema; puede gestionar todos los usuarios y tenants
`admin`	5	Administración del tenant; puede gestionar la mayoría de los recursos
`fde`	4	Field Development Engineer con acceso estándar: gestiona proyectos, comercios, operadores, rutas, audiencias y actividades
`supervisor`	3	Supervisa a los operadores de campo: consulta actividades, registra y edita resultados, y puede forzar un nuevo despacho de actividades fallidas
`operator`	2	Operador de campo con acceso acotado a las actividades que tiene asignadas: las consulta y registra sus resultados; también puede gestionar comercios
`viewer`	1 (mínimo)	Acceso de solo lectura a los datos del tenant

Permisos por Dominio

Dominio de Usuarios

Permiso	Descripción	Roles
`user:create`	Crear nuevos usuarios	`super_admin`, `admin`
`user:view`	Listar usuarios del tenant	`super_admin`, `admin`, `fde`, `supervisor`, `viewer`
`user:update`	Reemplazar los roles de un usuario (`PUT /api/user/:id/roles`)	`super_admin`, `admin`
`user:delete`	Ningún endpoint lo requiere hoy	`super_admin`, `admin`
`user:reset-password`	Restablecer la contraseña de otro usuario	`super_admin`, `admin`

Dominio de Tenants

Permiso	Descripción	Roles
`tenant:create`	Crear nuevos tenants	`super_admin`
`tenant:view`	Listar todos los tenants	`super_admin`, `admin`
`tenant:update`	Actualizar datos del tenant	`super_admin`
`tenant:delete`	Ningún endpoint lo requiere hoy	`super_admin`

Dominio de Proyectos

Permiso	Descripción	Roles
`project:create`	Crear proyectos junto con su audiencia raíz (`POST /api/projects`)	`super_admin`, `admin`, `fde`
`project:view`	Listar los proyectos del tenant (`GET /api/projects`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`project:update`	Renombrar proyectos (`PATCH /api/projects/:id`) y editar su audiencia raíz	`super_admin`, `admin`, `fde`

Dominio de Comercios

Permiso	Descripción	Roles
`commerce:manage`	CRUD completo sobre comercios, direcciones, usuarios y contactos (eliminar un comercio requiere `commerce:delete`)	`super_admin`, `admin`, `fde`, `operator`
`commerce:batch-upsert`	Carga masiva (batch upsert) de comercios desde sistemas externos (`POST /api/integration/commerces/batch-upsert`)	`super_admin`, `admin`

Dominio de Estados de Ciclo de Vida de Comercios

Permiso	Descripción	Roles
`commerce-lifecycle-snapshot:view`	Listar y consultar los estados de ciclo de vida de comercios, incluido el lookup por lote	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`commerce-lifecycle-snapshot:create`	Escribir estados de ciclo de vida de comercios: upsert individual y upsert por lote	`super_admin`, `admin`, `fde`, `supervisor`
`commerce-lifecycle-snapshot:sync`	Hoy ningún endpoint lo requiere (el upsert por lote requiere `commerce-lifecycle-snapshot:create`)	`super_admin`, `admin`, `fde`

Dominio de Operadores

Permiso	Descripción	Roles
`operator:manage`	CRUD completo sobre operadores (eliminar un operador requiere `operator:delete`)	`super_admin`, `admin`, `fde`
`operator:batch-upsert`	Carga masiva (batch upsert) de operadores desde sistemas externos (`POST /api/integration/operators/batch-upsert`)	`super_admin`, `admin`

Dominio de Rutas

Permiso	Descripción	Roles
`route:manage`	CRUD completo sobre rutas y asignaciones de operadores (eliminar una ruta requiere `route:delete`)	`super_admin`, `admin`, `fde`
`route:batch-upsert`	Carga masiva (batch upsert) de rutas desde sistemas externos (`POST /api/integration/routes/batch-upsert`)	`super_admin`, `admin`

Dominio de Actividades

Permiso	Descripción	Roles
`activity:view`	Listar y consultar actividades, resultados y configuraciones	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`activity:create`	Crear actividades (`POST /api/activities` y `POST /api/activities/bulk`)	`super_admin`, `admin`, `fde`
`activity:cancel`	Cancelar actividades	`super_admin`, `admin`, `fde`
`activity:dispatch`	Despachar manualmente actividades de tarea	`super_admin`, `admin`
`activity:force-retry-dispatch`	Forzar un nuevo despacho de una actividad `FAILED` (`PATCH /api/activities/:id/force-retry-dispatch`)	`super_admin`, `admin`, `supervisor`
`activity-config:manage`	Gestionar configuración de actividades (activity setup) y configuraciones de despacho	`super_admin`, `admin`

Dominio de Audiencias

Permiso	Descripción	Roles
`audience-criteria:create`	Crear audiencias (`POST /api/audience-criterias`)	`super_admin`, `admin`, `fde`
`audience-criteria:view`	Listar y consultar audiencias, y explorar su catálogo (`tables`, `tables/:tableName/columns`)	`super_admin`, `admin`, `fde`
`audience-criteria:update`	Actualizar audiencias (`PATCH /api/audience-criterias/:id`); editar la audiencia raíz requiere además `project:update`	`super_admin`, `admin`, `fde`
`audience-criteria:delete`	Eliminar audiencias (`DELETE /api/audience-criterias/:id`)	`super_admin`, `admin`, `fde`
`audience-criteria:view-sql`	Generar, validar y previsualizar el SQL de una audiencia	`super_admin`, `admin`, `fde`

Dominio de Filtros de Eventos

Permiso	Descripción	Roles
`event-criteria:create`	Crear filtros de eventos (`POST /api/event-criterias`)	`super_admin`, `admin`, `fde`
`event-criteria:view`	Listar y consultar filtros de eventos, y explorar su catálogo (`tables`, `tables/:tableName/columns`)	`super_admin`, `admin`, `fde`
`event-criteria:update`	Actualizar filtros de eventos (`PATCH /api/event-criterias/:id`)	`super_admin`, `admin`, `fde`
`event-criteria:delete`	Eliminar filtros de eventos (`DELETE /api/event-criterias/:id`)	`super_admin`, `admin`, `fde`
`event-criteria:view-sql`	Generar, validar y previsualizar el SQL de un filtro de eventos	`super_admin`, `admin`, `fde`

Dominio de Activity Generation y Ciclo de Vida

Permiso	Descripción	Roles
`activity-generation-config:view`	Ver AGCs y sus pilares de ciclo de vida (incl. los `configHashes` por pilar)	`super_admin`, `admin`
`activity-generation-config:create`	Crear una AGC con sus 3 pilares de ciclo de vida	`super_admin`, `admin`
`activity-generation-config:update`	Actualizar metadatos de la AGC, reemplazar pilares de ciclo de vida in-place, publicar y pausar	`super_admin`, `admin`
`activity-generation-config:delete`	Archivar una AGC (cascada a sus lifecycle configs)	`super_admin`, `admin`
`lifecycle-config:view`	Ver los lifecycle configs de solo lectura (activación / engagement / resurrección)	`super_admin`, `admin`
`lifecycle-config:delete`	Interno — habilita el archivado/restauración de lifecycle en la cascada de papelera	`super_admin`, `admin`

Los lifecycle configs no tienen permisos standalone de creación/edición/borrado: un lifecycle config se crea y edita solo a través del flujo del AGC, restringido por activity-generation-config:create / activity-generation-config:update.

Dominio de Proveedores de Despacho

Permiso	Descripción	Roles
`dispatch-provider:manage`	Editar las definiciones de canal de un proveedor de despacho: mapeo de payload y ajustes recomendados, y si el mapeo es obligatorio (`PATCH /api/dispatch-providers/:providerId/channel-definitions/:definitionId`)	`super_admin`

Dominio de Consulta de Datos

Permiso	Descripción	Roles
`data-query:view`	Leer la metadata del catálogo de datos: tablas y sus columnas (`GET /api/data-query/tables`, `GET /api/data-query/tables/:tableName/columns`)	`super_admin`, `admin`, `fde`

Dominio de API Keys

Permiso	Descripción	Roles
`api-key:manage`	Crear, listar, revocar y editar los permisos de API keys	`super_admin`, `admin`

Dominio de Resultados de Actividades

Permiso	Descripción	Roles
`activity-result:submit`	Registrar resultados de actividades (`POST /api/activity-results/tasks` y `POST /api/integration/activity-results/tasks`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`
`activity-result:edit`	Editar resultados de actividades (`PATCH /api/activity-results/tasks/:id`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`
`activity-result:sync-stream`	Leer el stream incremental de sincronización de resultados de tareas (`GET /api/activity-results/tasks/sync`)	`super_admin`, `admin`

Dominio de Papelera y Eliminación

Permiso	Descripción	Roles
`trash:view`	Ver los registros archivados en la papelera y restaurarlos (`/api/trash`). Ver el detalle de un registro o la vista previa de su cascada, y restaurarlo, requiere además el permiso que elimina ese tipo de registro (por ejemplo, `commerce:delete`). Eliminar un registro de la papelera de forma definitiva está reservado a `super_admin`	`super_admin`, `admin`, `fde`
`trash:manage-settings`	Ver y cambiar la configuración de retención de la papelera del tenant (`GET` y `PATCH /api/trash/settings`)	`super_admin`, `admin`
`commerce:delete`	Eliminar comercios, que pasan a la papelera (`DELETE /api/commerces/:id`)	`super_admin`, `admin`, `fde`
`operator:delete`	Eliminar operadores, que pasan a la papelera (`DELETE /api/operators/:id`)	`super_admin`, `admin`, `fde`
`route:delete`	Eliminar rutas, que pasan a la papelera (`DELETE /api/routes/:id`)	`super_admin`, `admin`, `fde`
`supervisor:delete`	Eliminar supervisores, que pasan a la papelera (`DELETE /api/supervisors/:id`)	`super_admin`, `admin`, `fde`

Acceso máquina-a-máquina (M2M) para el cómputo

El motor de retención que calcula los estados de ciclo de vida de comercios lee las AGCs de forma programática. Usa una API key (sin mecanismo de auth nuevo) que lleva activity-generation-config:view. Con ese permiso llama a GET /api/activity-generation-configs y GET /api/activity-generation-configs/:id para leer cada pilar y sus configHashes (para detectar de forma barata cuándo cambió una config), y luego escribe los estados calculados vía commerce lifecycle snapshots. Los dos endpoints de AGC son project-scoped: con una clave de tenant, cada llamada envía x-project-id (sin él la API responde 400 — Falta el header obligatorio x-project-id.), y una clave de proyecto solo lee las AGCs de su propio proyecto — ver Alcance de la clave.

Cómo los Permisos Restringen los Endpoints

Para rutas protegidas, la API verifica cada solicitud en este orden:

Autenticación — El access token JWT o la API key es válido (toda ruta protegida)
Tenant — El usuario pertenece al tenant solicitado
Proyecto — En los endpoints project-scoped, el proyecto activo es válido (ver Autenticación → Contexto de Proyecto)
Permisos — El usuario tiene los permisos requeridos

Cada página de endpoint en la referencia de API lista el permiso requerido (ej., Auth: Requerido — permiso activity:create).

Aplicación de la Jerarquía de Roles

Los usuarios no pueden modificar los roles de usuarios del mismo nivel o superior
Los usuarios no pueden restablecer contraseñas de usuarios del mismo nivel o superior
Los usuarios no pueden asignar un rol igual o superior al propio

En los tres casos la API responde 403.

Contexto de Tenant

La mayoría de los endpoints requieren un contexto de tenant:

Auth JWT: proporcionar el header x-tenant-id con el UUID del tenant
Auth API key: el tenant se resuelve automáticamente desde la key

El sistema valida que el usuario autenticado pertenezca al tenant solicitado antes de continuar.

Los endpoints project-scoped necesitan además el proyecto (ver Autenticación → Contexto de Proyecto):

Auth JWT y claves de tenant: proporcionar el header x-project-id con el UUID del proyecto. En los endpoints project-optional el header es opcional y acota la solicitud a ese proyecto
Claves de proyecto: la clave siempre trabaja en su propio proyecto, así que el header no hace falta (ver Alcance de la clave)