Skip to content
Guia da Central de Ajuda · Definições de conta e área
3 min de leituraVerificado 2026-11-16

Membros da equipa e permissões

Convide colegas com perfis RBAC Admin/Editor/Operador, restrição por projeto e 2FA obrigatória por perfil.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
RBAC MULTINÍVEL E DELIMITAÇÃO POR MODELO
ETAPA 01 NÍVEL 1: GOVERNAÇÃO DA ORGANIZAÇÃO
Funções Organization: OWNER | ADMIN | MEMBER
Controla provisionamento multi-espaço, faturação consolidada e SSO/SAML
ETAPA 02 NÍVEL 2: HIERARQUIA DE FUNÇÕES DE ESPAÇO
Team Permissions API (/api/v1/rbac/roles)
Funções de sistema: Workspace Admin, Campaign Editor, `Scanner Operator
Funções personalizadas: POST/api/v1/rbac/roles com escopos granulares
Herança de funções: GET/api/v1/rbac/roles/:roleId/inheritance
ETAPA 03 NÍVEL 3: RESTRIÇÃO DE ACESSO A MODELOS
POST/api/v1/rbac/roles/:roleId/template-access
Restringe titulares da função a listas explícitas de templateId
Imposto no servidor em pesquisa de cartões, envios, leituras e exportações

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-access garante 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ÂmbitoCapacidades e Permissões Principais
Organization OWNERTodos os espaços da organizaçãoControlo 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 ADMINEspaços atribuídos / todosGestã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 únicoCriaçã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 OperatorEspaço único / Modelos autorizadosEmissã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

EndpointVerbo HTTPDescrição
/api/v1/rbac/rolesGETLista todas as funções incorporadas e personalizadas definidas no espaço ativo.
/api/v1/rbac/rolesPOSTCria uma função RBAC personalizada com tokens de permissão explícitos e herança opcional de função pai.
/api/v1/rbac/roles/:roleIdPUTAtualiza o nome, descrição, política requireTwoFactor ou conjunto de permissões de uma função personalizada.
/api/v1/rbac/roles/:roleIdDELETEElimina uma função personalizada (falha em segurança se ainda existirem membros ativos atribuídos).
/api/v1/rbac/roles/:roleId/inheritanceGETDevolve o grafo de herança pai-filho para a função especificada.
/api/v1/rbac/roles/:roleId/inherited-permissionsGETCalcula a união efetiva de permissões diretas e permissões herdadas das funções pai.
/api/v1/rbac/roles/:roleId/template-accessPOSTAssocia a função a uma lista explícita permitida de templateIds (accessMode: 'SCOPED').

Criar uma Função Personalizada com Herança

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 Resposta (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 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:

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"
}

Documentação Relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.