Descripción general
Passinstance implementa un motor jerárquico de Control de Acceso Basado en Roles (RBAC) de mínimos privilegios (Team Permissions API en /api/v1/rbac/*, gestionado visualmente en el Panel desde Configuración del espacio de trabajo -> Miembros y roles: /settings/workspace/members, /settings/workspace/roles y /settings/workspace/roles/permission-matrix) que separa el gobierno a nivel de organización (OrganizationMemberRole: OWNER | ADMIN | MEMBER) de los roles operativos del espacio de trabajo. Los administradores pueden invitar miembros (POST /api/v1/users/invitations), crear roles personalizados con árboles de herencia, exigir autenticación en dos factores (2FA) por rol y restringir operadores a plantillas de pase concretas (template-access).
Arquitectura RBAC multinivel y alcance por plantilla
Importante: Las comprobaciones de autorización se aplican estrictamente en el servidor en las capas de controlador y servicio de NestJS. Restringir un rol personalizado mediante
template-accessgarantiza que el operador no pueda consultar, modificar ni exportar pases de plantillas no autorizadas aunque llame directamente a la API REST.
Roles de Organización frente a roles de Espacio de trabajo
Passinstance diferencia entre la membresía global de Organización y los permisos dentro de cada Espacio de trabajo (Customer):
| Nivel y rol | Ámbito | Capacidades y permisos principales |
|---|---|---|
Organization OWNER | Todos los espacios de la organización | Control total sobre resúmenes consolidados de facturación (GET /api/v1/organizations/current/billing-summary), creación/eliminación de espacios, configuración SAML 2.0 SSO y transferencia de propiedad. |
Organization ADMIN | Espacios asignados / todos | Gestión de invitaciones del equipo, configuración del espacio, certificados de firma Apple/Google, claves API (api:keys-manage) y webhooks. |
Workspace Editor (MEMBER) | Un espacio de trabajo | Creación y edición de plantillas de pase, configuración de mecánicas y niveles, ejecución de importaciones CSV por lotes y campañas en el Centro de envíos. |
Workspace Operator | Un espacio / Plantillas autorizadas | Emisión o consulta de pases individuales, manejo de escáneres web/móviles y visualización de informes de escaneo autorizados sin acceso a facturación ni claves API. |
Roles personalizados, herencia y alcances de permiso (Team Permissions API)
Cuando los roles integrados resultan demasiado amplios para equipos especializados (por ejemplo, una agencia externa de marketing o gerentes regionales), los administradores del espacio pueden crear roles propios en Cuenta → Miembros del equipo → Roles y permisos.
Endpoints principales de RBAC
| Endpoint | Verbo HTTP | Descripción |
|---|---|---|
/api/v1/rbac/roles | GET | Lista todos los roles integrados y personalizados definidos en el espacio activo. |
/api/v1/rbac/roles | POST | Crea un rol RBAC personalizado con tokens de permiso explícitos y herencia opcional de rol padre. |
/api/v1/rbac/roles/:roleId | PUT | Actualiza el nombre, descripción, política requireTwoFactor o conjunto de permisos de un rol propio. |
/api/v1/rbac/roles/:roleId | DELETE | Elimina un rol propio (falla de forma segura si aún tiene miembros activos asignados). |
/api/v1/rbac/roles/:roleId/inheritance | GET | Devuelve el grafo de herencia padre-hijo del rol especificado. |
/api/v1/rbac/roles/:roleId/inherited-permissions | GET | Calcula la unión efectiva de permisos directos y heredados de roles padre. |
/api/v1/rbac/roles/:roleId/template-access | POST | Vincula el rol a una lista permitida explícita de templateIds (accessMode: 'SCOPED'). |
Crear un rol personalizado con herencia
POST /api/v1/rbac/roles HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Regional Event Coordinator",
"description": "Can manage passes and view scan analytics for assigned event templates only.",
"parentRoleId": "rol_builtin_operator",
"requireTwoFactor": true,
"permissions": [
"passes:read",
"passes:write",
"passes:export",
"scans:read",
"analytics:read"
]
}
Payload de respuesta (201 Created)
{
"id": "rol_01933210-8b44-7c00-9e12-445566778899",
"name": "Regional Event Coordinator",
"description": "Can manage passes and view scan analytics for assigned event templates only.",
"isSystemRole": false,
"parentRoleId": "rol_builtin_operator",
"requireTwoFactor": true,
"permissions": [
"passes:read",
"passes:write",
"passes:export",
"scans:read",
"analytics:read"
],
"createdAt": "2026-11-15T23:34:30.000Z"
}
Restringir un rol a plantillas concretas (template-access)
Para aislar un rol personalizado de modo que sus miembros solo vean y gestionen pases de plantillas concretas:
POST /api/v1/rbac/roles/rol_01933210-8b44-7c00-9e12-445566778899/template-access HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"accessMode": "SCOPED",
"templateIds": [
"b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"c8e12a90-41b2-4f00-8a11-998877665544"
],
"allowedActions": ["READ", "ISSUE_PASS", "SCAN_PASS", "EXPORT_DATA"]
}
{
"roleId": "rol_01933210-8b44-7c00-9e12-445566778899",
"accessMode": "SCOPED",
"scopedTemplateCount": 2,
"templateIds": [
"b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"c8e12a90-41b2-4f00-8a11-998877665544"
],
"updatedAt": "2026-11-15T23:35:02.000Z"
}
Documentación relacionada
-
Gestione estructuras multiespacio de agencias en Gestión multicliente.
-
Configure TOTP 2FA personal en Perfil y preferencias.
-
Revise exportaciones de auditoría en Seguridad de la cuenta y acceso.
