Roles y Permisos
Jerarquía de roles, permisos y cómo restringen los endpoints de la API.
Reten implementa Control de Acceso Basado en Roles (RBAC) jerárquico con permisos granulares agrupados por dominio. Las tablas siguientes cubren los dominios más comunes; el conjunto completo de permisos es mayor y aditivo.
Jerarquía de Roles
SUPER_ADMIN (máximo)
│
▼
ADMIN
│
▼
FDE
│
▼
VIEWER (mínimo)Los roles superiores heredan todos los permisos de los roles inferiores y pueden gestionar usuarios de su mismo nivel o inferior.
Roles
| Rol | Nivel | Descripción |
|---|---|---|
SUPER_ADMIN | Máximo | Acceso total al sistema; puede gestionar todos los usuarios y tenants |
ADMIN | Alto | Administración del tenant; puede gestionar la mayoría de los recursos |
FDE | Medio | Operaciones de campo; puede crear actividades y consultar datos |
VIEWER | Mínimo | Acceso de solo lectura a los datos del tenant |
Permisos por Dominio
Dominio de Usuarios
| Permiso | Descripción | Roles |
|---|---|---|
CREATE_USER | Crear nuevos usuarios | SUPER_ADMIN, ADMIN |
VIEW_USERS | Listar usuarios del tenant | SUPER_ADMIN, ADMIN, FDE |
UPDATE_USER | Actualizar datos y roles de usuarios | SUPER_ADMIN, ADMIN |
DELETE_USER | Eliminar usuarios | SUPER_ADMIN |
RESET_USER_PASSWORD | Restablecer la contraseña de otro usuario | SUPER_ADMIN, ADMIN |
Dominio de Tenants
| Permiso | Descripción | Roles |
|---|---|---|
CREATE_TENANT | Crear nuevos tenants | SUPER_ADMIN |
VIEW_TENANTS | Listar todos los tenants | SUPER_ADMIN, ADMIN |
UPDATE_TENANT | Actualizar datos del tenant | SUPER_ADMIN |
DELETE_TENANT | Eliminar tenants | SUPER_ADMIN |
Dominio de Comercios
| Permiso | Descripción | Roles |
|---|---|---|
MANAGE_COMMERCES | CRUD completo sobre comercios, direcciones, usuarios y contactos | SUPER_ADMIN, ADMIN, FDE |
SYNC_COMMERCES | Sincronización masiva de comercios desde sistemas externos | SUPER_ADMIN, ADMIN |
Dominio de Operadores
| Permiso | Descripción | Roles |
|---|---|---|
MANAGE_OPERATORS | CRUD completo sobre operadores | SUPER_ADMIN, ADMIN, FDE |
SYNC_OPERATORS | Sincronización masiva de operadores desde sistemas externos | SUPER_ADMIN, ADMIN |
Dominio de Rutas
| Permiso | Descripción | Roles |
|---|---|---|
MANAGE_ROUTES | CRUD completo sobre rutas y asignaciones de operadores | SUPER_ADMIN, ADMIN, FDE |
Dominio de Actividades
| Permiso | Descripción | Roles |
|---|---|---|
VIEW_ACTIVITIES | Listar y consultar actividades, resultados y configuraciones | SUPER_ADMIN, ADMIN, FDE, VIEWER |
CREATE_ACTIVITY | Crear actividades y resultados | SUPER_ADMIN, ADMIN, FDE |
CANCEL_ACTIVITY | Cancelar actividades | SUPER_ADMIN, ADMIN |
DISPATCH_ACTIVITY | Despachar manualmente actividades de tarea | SUPER_ADMIN, ADMIN |
MANAGE_ACTIVITY_CONFIG | Gestionar configuración de actividades (activity setup) y configuraciones de despacho | SUPER_ADMIN, ADMIN |
Dominio de Activity Generation y Ciclo de Vida
| Permiso | value | Descripción | Roles |
|---|---|---|---|
VIEW_ACTIVITY_GENERATION_CONFIGS | activity-generation-config:view | Ver AGCs y sus pilares de ciclo de vida (incl. los configHashes por pilar) | SUPER_ADMIN, ADMIN |
CREATE_ACTIVITY_GENERATION_CONFIG | activity-generation-config:create | Crear una AGC con sus 3 pilares de ciclo de vida | SUPER_ADMIN, ADMIN |
UPDATE_ACTIVITY_GENERATION_CONFIG | activity-generation-config:update | Actualizar metadata de la AGC y reemplazar pilares in-place | SUPER_ADMIN, ADMIN |
DELETE_ACTIVITY_GENERATION_CONFIG | activity-generation-config:delete | Archivar una AGC (cascada a sus lifecycle configs) | SUPER_ADMIN, ADMIN |
VIEW_LIFECYCLE_CONFIGS | lifecycle-config:view | Ver los lifecycle configs de solo lectura (activación / engagement / resurrección) | SUPER_ADMIN, ADMIN |
DELETE_LIFECYCLE_CONFIG | 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 CREATE_ACTIVITY_GENERATION_CONFIG / UPDATE_ACTIVITY_GENERATION_CONFIG.
Dominio de API Keys
| Permiso | Descripción | Roles |
|---|---|---|
MANAGE_API_KEYS | Crear, listar y revocar API keys | SUPER_ADMIN, ADMIN |
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 existente scoped al tenant (sin mecanismo de auth nuevo) que lleva VIEW_ACTIVITY_GENERATION_CONFIGS (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.
Cómo los Permisos Restringen los Endpoints
Para rutas protegidas, los guards se ejecutan en este orden:
- JwtAuthGuard — Valida el access token JWT o API key (global)
- TenantGuard — Valida que el usuario pertenezca al tenant solicitado
- PermissionsGuard — Verifica que el usuario tenga los permisos requeridos
Cada página de endpoint en la referencia de API lista el permiso requerido (ej., Auth: Requerido — permiso CREATE_ACTIVITY).
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 roles superiores al propio
Contexto de Tenant
La mayoría de los endpoints requieren un contexto de tenant:
- Auth JWT: proporcionar el header
x-tenant-idcon 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.