Skip to content
Guida del Centro assistenza · Impostazioni account e workspace
3 min di letturaVerificato 2026-11-16

Membri del team e permessi

Invita collaboratori con ruoli RBAC Admin/Editor/Operatore, limiti per progetto e 2FA per ruolo.

In questa guida

Panoramica

Passinstance implementa un motore gerarchico di Controllo degli accessi basato sui ruoli (RBAC) fondato sul principio del privilegio minimo (Team Permissions API su /api/v1/rbac/*, gestito visivamente nella Dashboard in Impostazioni del workspace -> Membri e ruoli: /settings/workspace/members, /settings/workspace/roles e /settings/workspace/roles/permission-matrix) che separa la governance a livello di Organizzazione (OrganizationMemberRole: OWNER | ADMIN | MEMBER) dai ruoli operativi a livello di Workspace. Gli amministratori possono invitare membri del team (POST /api/v1/users/invitations), creare ruoli personalizzati con alberi di ereditarietà, imporre l'autenticazione a due fattori (2FA) per singolo ruolo e limitare gli operatori a specifici modelli di pass (template-access).

Architettura RBAC multilivello e limitazione dell'ambito per modello

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RBAC MULTILIVELLO E LIMITAZIONE ACCESSI PER MODELLO
FASE 01 LIVELLO 1: GOVERNANCE DELL'ORGANIZZAZIONE
Ruoli Organization: OWNER | ADMIN | MEMBER
Controlla provisioning multi-workspace, fatturazione consolidata e SSO/SAML
FASE 02 LIVELLO 2: GERARCHIA DEI RUOLI DEL WORKSPACE
Team Permissions API (/api/v1/rbac/roles)
Ruoli di sistema: Workspace Admin, Campaign Editor, Scanner Operator
Ruoli personalizzati: POST/api/v1/rbac/roles con permessi granulari
Ereditarietà dei ruoli: GET/api/v1/rbac/roles/:roleId/inheritance
FASE 03 LIVELLO 3: LIMITAZIONE DEGLI ACCESSI A LIVELLO DI MODELLO
POST/api/v1/rbac/roles/:roleId/template-access
Limita i titolari del ruolo a elenchi consentiti espliciti di templateId
Applicato lato server su ricerca pass, invii, scansioni ed esportazioni

Importante: I controlli di autorizzazione vengono applicati rigorosamente lato server a livello dei controller e dei servizi NestJS. La limitazione di un ruolo personalizzato tramite template-access garantisce che l'operatore non possa interrogare, modificare o esportare pass appartenenti a modelli non autorizzati nemmeno chiamando direttamente l'API REST.

Ruoli dell'Organizzazione rispetto ai ruoli del Workspace

Passinstance distingue tra l'appartenenza all'Organizzazione ombrello e le autorizzazioni del singolo Workspace (Customer):

Livello e ruoloAmbitoFunzionalità e autorizzazioni principali
OWNER dell'OrganizzazioneTutti i workspace nell'OrganizzazioneControllo completo sui riepiloghi di fatturazione dell'organizzazione (GET /api/v1/organizations/current/billing-summary), creazione ed eliminazione dei workspace, configurazione SSO SAML 2.0 e trasferimenti di proprietà.
ADMIN dell'OrganizzazioneWorkspace assegnati / Tutti i workspaceGestione degli inviti del team, impostazioni del workspace, certificati di firma Apple/Google, chiavi API (api:keys-manage) e webhook.
Editor del Workspace (MEMBER)Singolo workspaceCreazione e modifica dei modelli di pass, configurazione di meccaniche e livelli, esecuzione di importazioni batch CSV e gestione delle campagne nel Centro di recapito.
Operator del WorkspaceSingolo workspace / Modelli autorizzatiEmissione o ricerca di singoli pass, utilizzo degli scanner di convalida web/mobile e consultazione dei report di scansione autorizzati senza accesso alla fatturazione o alle chiavi API.

Ruoli personalizzati, ereditarietà e ambiti di autorizzazione (Team Permissions API)

Quando i ruoli predefiniti risultano troppo ampi per team specializzati (ad esempio, un'agenzia di marketing esterna o un responsabile di punto vendita regionale), gli amministratori del workspace possono definire ruoli personalizzati in Account → Membri del team → Ruoli e autorizzazioni.

Endpoint API RBAC principali

EndpointVerbo HTTPDescrizione
/api/v1/rbac/rolesGETElenca tutti i ruoli predefiniti e personalizzati definiti all'interno del workspace attivo.
/api/v1/rbac/rolesPOSTCrea un ruolo RBAC personalizzato con token di autorizzazione espliciti ed ereditarietà opzionale da un ruolo padre.
/api/v1/rbac/roles/:roleIdPUTAggiorna il nome, la descrizione, il criterio requireTwoFactor o il set di autorizzazioni di un ruolo personalizzato.
/api/v1/rbac/roles/:roleIdDELETEElimina un ruolo personalizzato (si interrompe in sicurezza se vi sono ancora membri attivi del team assegnati al ruolo).
/api/v1/rbac/roles/:roleId/inheritanceGETRestituisce il grafo di ereditarietà padre-figlio per il ruolo specificato.
/api/v1/rbac/roles/:roleId/inherited-permissionsGETCalcola l'unione effettiva delle autorizzazioni dirette e di quelle ereditate dai ruoli padre.
/api/v1/rbac/roles/:roleId/template-accessPOSTVincola il ruolo a un elenco consentito esplicito di templateIds (accessMode: 'SCOPED').

Creazione di un ruolo personalizzato con ereditarietà

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 di risposta (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"
}

Limitazione di un ruolo a modelli specifici (template-access)

Per isolare un ruolo personalizzato affinché i suoi membri possano visualizzare e gestire esclusivamente i pass appartenenti a modelli specifici:

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

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.