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
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-accessgarantisce 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 ruolo | Ambito | Funzionalità e autorizzazioni principali |
|---|---|---|
OWNER dell'Organizzazione | Tutti i workspace nell'Organizzazione | Controllo 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'Organizzazione | Workspace assegnati / Tutti i workspace | Gestione degli inviti del team, impostazioni del workspace, certificati di firma Apple/Google, chiavi API (api:keys-manage) e webhook. |
Editor del Workspace (MEMBER) | Singolo workspace | Creazione 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 Workspace | Singolo workspace / Modelli autorizzati | Emissione 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
| Endpoint | Verbo HTTP | Descrizione |
|---|---|---|
/api/v1/rbac/roles | GET | Elenca tutti i ruoli predefiniti e personalizzati definiti all'interno del workspace attivo. |
/api/v1/rbac/roles | POST | Crea un ruolo RBAC personalizzato con token di autorizzazione espliciti ed ereditarietà opzionale da un ruolo padre. |
/api/v1/rbac/roles/:roleId | PUT | Aggiorna il nome, la descrizione, il criterio requireTwoFactor o il set di autorizzazioni di un ruolo personalizzato. |
/api/v1/rbac/roles/:roleId | DELETE | Elimina un ruolo personalizzato (si interrompe in sicurezza se vi sono ancora membri attivi del team assegnati al ruolo). |
/api/v1/rbac/roles/:roleId/inheritance | GET | Restituisce il grafo di ereditarietà padre-figlio per il ruolo specificato. |
/api/v1/rbac/roles/:roleId/inherited-permissions | GET | Calcola l'unione effettiva delle autorizzazioni dirette e di quelle ereditate dai ruoli padre. |
/api/v1/rbac/roles/:roleId/template-access | POST | Vincola il ruolo a un elenco consentito esplicito di templateIds (accessMode: 'SCOPED'). |
Creazione di un ruolo personalizzato con ereditarietà
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)
{
"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:
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"
}
Documentazione correlata
-
Gestisca le strutture multi-workspace per le agenzie in Gestione multi-cliente.
-
Configuri la 2FA TOTP personale in Profilo e preferenze.
-
Consulti le esportazioni dei log di audit in Sicurezza dell'account e controllo degli accessi.
