Skip to content
Guía del Centro de ayuda · Ajustes de cuenta y espacio
3 min de lecturaVerificado 2026-11-16

Miembros del equipo y permisos

Invita colaboradores con roles Admin/Editor/Operador, alcances restringidos y 2FA obligatorio según rol.

En esta guía

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
RBAC MULTINIVEL Y ALCANCE POR PLANTILLA
ETAPA 01 NIVEL 1: GOBIERNO DE LA ORGANIZACIÓN
Roles de Organization: OWNER | ADMIN | MEMBER
Controla provisión multiespacio, facturación consolidada y SSO/SAML
ETAPA 02 NIVEL 2: JERARQUÍA DE ROLES DE ESPACIO
Team Permissions API (/api/v1/rbac/roles)
Roles del sistema: Workspace Admin, Campaign Editor, Scanner Operator
Roles propios: POST/api/v1/rbac/roles con alcances granulares
Herencia de roles: GET/api/v1/rbac/roles/:roleId/inheritance
ETAPA 03 NIVEL 3: RESTRICCIÓN DE ACCESO A PLANTILLAS
POST/api/v1/rbac/roles/:roleId/template-access
Limita a los titulares del rol a listas explícitas de templateId
Aplicado en servidor en búsqueda de pases, envíos, escaneos y exportaciones

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-access garantiza 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ÁmbitoCapacidades y permisos principales
Organization OWNERTodos los espacios de la organizaciónControl 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 ADMINEspacios asignados / todosGestió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 trabajoCreació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 OperatorUn espacio / Plantillas autorizadasEmisió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

EndpointVerbo HTTPDescripción
/api/v1/rbac/rolesGETLista todos los roles integrados y personalizados definidos en el espacio activo.
/api/v1/rbac/rolesPOSTCrea un rol RBAC personalizado con tokens de permiso explícitos y herencia opcional de rol padre.
/api/v1/rbac/roles/:roleIdPUTActualiza el nombre, descripción, política requireTwoFactor o conjunto de permisos de un rol propio.
/api/v1/rbac/roles/:roleIdDELETEElimina un rol propio (falla de forma segura si aún tiene miembros activos asignados).
/api/v1/rbac/roles/:roleId/inheritanceGETDevuelve el grafo de herencia padre-hijo del rol especificado.
/api/v1/rbac/roles/:roleId/inherited-permissionsGETCalcula la unión efectiva de permisos directos y heredados de roles padre.
/api/v1/rbac/roles/:roleId/template-accessPOSTVincula el rol a una lista permitida explícita de templateIds (accessMode: 'SCOPED').

Crear un rol personalizado con herencia

HTTP
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)

JSON
{
  "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:

HTTP
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"]
}
JSON
{
  "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

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.