Visão geral
O Passinstance implementa um motor hierárquico de Controlo de Acesso Baseado em Funções (RBAC) com privilégio mínimo (Team Permissions API em /api/v1/rbac/*, gerido visualmente no Painel em Definições do Espaço de Trabalho -> Membros e Funções: /settings/workspace/members, /settings/workspace/roles e /settings/workspace/roles/permission-matrix) que separa a governação ao nível da Organização (OrganizationMemberRole: OWNER | ADMIN | MEMBER) das funções operacionais do Espaço de Trabalho. Os administradores podem convidar membros (POST /api/v1/users/invitations), criar funções personalizadas com árvores de herança, exigir Autenticação de Dois Fatores (2FA) por função e restringir operadores a modelos de cartão específicos (template-access).
Arquitetura RBAC Multinível e Delimitação por Modelo
Importante: As verificações de autorização são aplicadas rigorosamente do lado do servidor nas camadas de controlador e serviço NestJS. Restringir uma função personalizada através de
template-accessgarante que o operador não possa consultar, alterar nem exportar cartões pertencentes a modelos não autorizados, mesmo invocando diretamente a API REST.
Funções de Organização vs. Funções de Espaço de Trabalho
O Passinstance distingue entre a pertença global à Organização e as permissões num Espaço de Trabalho (Customer) individual:
| Nível e Função | Âmbito | Capacidades e Permissões Principais |
|---|---|---|
Organization OWNER | Todos os espaços da organização | Controlo total sobre resumos consolidados de faturação (GET /api/v1/organizations/current/billing-summary), criação/eliminação de espaços, configuração SSO SAML 2.0 e transferência de titularidade. |
Organization ADMIN | Espaços atribuídos / todos | Gestão de convites de equipa, definições do espaço, certificados de assinatura Apple/Google, chaves de API (api:keys-manage) e webhooks. |
Workspace Editor (MEMBER) | Espaço único | Criação e edição de modelos de cartão, configuração de mecânicas e patamares, execução de importações CSV em lote e campanhas no Centro de Entregas. |
Workspace Operator | Espaço único / Modelos autorizados | Emissão ou consulta de cartões individuais, operação de leitores web/móveis e consulta de relatórios de leitura autorizados sem acesso a faturação ou chaves de API. |
Funções Personalizadas, Herança e Escopos de Permissão (Team Permissions API)
Quando as funções incorporadas são demasiado amplas para equipas especializadas (por exemplo, uma agência de marketing externa ou gestores regionais de loja), os administradores podem definir funções personalizadas em Conta → Membros da Equipa → Funções e Permissões.
Endpoints Principais de RBAC
| Endpoint | Verbo HTTP | Descrição |
|---|---|---|
/api/v1/rbac/roles | GET | Lista todas as funções incorporadas e personalizadas definidas no espaço ativo. |
/api/v1/rbac/roles | POST | Cria uma função RBAC personalizada com tokens de permissão explícitos e herança opcional de função pai. |
/api/v1/rbac/roles/:roleId | PUT | Atualiza o nome, descrição, política requireTwoFactor ou conjunto de permissões de uma função personalizada. |
/api/v1/rbac/roles/:roleId | DELETE | Elimina uma função personalizada (falha em segurança se ainda existirem membros ativos atribuídos). |
/api/v1/rbac/roles/:roleId/inheritance | GET | Devolve o grafo de herança pai-filho para a função especificada. |
/api/v1/rbac/roles/:roleId/inherited-permissions | GET | Calcula a união efetiva de permissões diretas e permissões herdadas das funções pai. |
/api/v1/rbac/roles/:roleId/template-access | POST | Associa a função a uma lista explícita permitida de templateIds (accessMode: 'SCOPED'). |
Criar uma Função Personalizada com Herança
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 Resposta (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 uma Função a Modelos Específicos (template-access)
Para isolar uma função personalizada para que os seus membros apenas visualizem e giram cartões pertencentes a modelos específicos:
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"
}
Documentação Relacionada
-
Gira estruturas multi-espaço de agências em Gestão Multicliente.
-
Configure a 2FA TOTP pessoal em Perfil e Preferências.
-
Consulte exportações do registo de auditoria em Segurança da Conta e Acesso.
