Überblick
Passinstance implementiert eine hierarchische Role-Based Access Control (RBAC)-Engine nach dem Minimalprinzip (Team Permissions API unter /api/v1/rbac/*, visuell im Dashboard unter Workspace-Einstellungen -> Mitglieder & Rollen: /settings/workspace/members, /settings/workspace/roles und /settings/workspace/roles/permission-matrix), die zwischen Organisations-Governance (OrganizationMemberRole: OWNER | ADMIN | MEMBER) und operativen Workspace-Rollen unterscheidet. Administratoren können Teammitglieder einladen (POST /api/v1/users/invitations), benutzerdefinierte Rollen mit Vererbungshierarchien erstellen, Zwei-Faktor-Authentifizierung (2FA) pro Rolle vorschreiben und Bediener auf bestimmte Pass-Vorlagen einschränken (template-access).
Mehrstufige RBAC- & Vorlagenzugriffs-Architektur
Wichtig: Autorisierungsprüfungen werden strikt serverseitig in der NestJS-Controller- und Serviceschicht durchgesetzt. Durch die Einschränkung einer benutzerdefinierten Rolle über
template-accessist sichergestellt, dass ein Bediener selbst bei direkten REST-API-Aufrufen keine Pässe nicht freigegebener Vorlagen abfragen, ändern oder exportieren kann.
Organisationsrollen vs. Workspace-Rollen
Passinstance unterscheidet zwischen übergreifender Organisationsmitgliedschaft und den Berechtigungen innerhalb eines einzelnen Workspace (Customer):
| Ebene & Rolle | Geltungsbereich | Kernfunktionen & Berechtigungen |
|---|---|---|
Organization OWNER | Alle Workspaces der Organisation | Vollständige Kontrolle über konsolidierte Organisationsabrechnung (GET /api/v1/organizations/current/billing-summary), Erstellung/Löschung von Workspaces, SAML-2.0-SSO und Übertragung der Eigentümerschaft. |
Organization ADMIN | Zugewiesene / alle Workspaces | Verwaltung von Teameinladungen, Workspace-Einstellungen, Apple-/Google-Signaturzertifikaten, API-Schlüsseln (api:keys-manage) und Webhooks. |
Workspace Editor (MEMBER) | Einzelner Workspace | Erstellung und Bearbeitung von Pass-Vorlagen, Konfiguration von Mechaniken und Stufen, Ausführung von CSV-Stapelimporten sowie Delivery-Center-Kampagnen. |
Workspace Operator | Einzelner Workspace / Freigegebene Vorlagen | Einzelne Pässe ausstellen oder nachschlagen, Web-/Mobile-Validierungsscanner bedienen und freigegebene Scanberichte ohne Zugriff auf Abrechnung oder API-Schlüssel einsehen. |
Benutzerdefinierte Rollen, Vererbung & Berechtigungen (Team Permissions API)
Wenn vordefinierte Rollen für spezialisierte Teams (z. B. eine externe Marketingagentur oder regionale Filialleiter) zu weit gefasst sind, können Workspace-Administratoren unter Konto → Teammitglieder → Rollen & Berechtigungen eigene Rollen definieren.
Zentrale RBAC-API-Endpunkte
| Endpunkt | HTTP-Verb | Beschreibung |
|---|---|---|
/api/v1/rbac/roles | GET | Listet alle System- und benutzerdefinierten Rollen im aktiven Workspace auf. |
/api/v1/rbac/roles | POST | Erstellt eine eigene RBAC-Rolle mit expliziten Berechtigungs-Tokens und optionaler Elternrollen-Vererbung. |
/api/v1/rbac/roles/:roleId | PUT | Aktualisiert Namen, Beschreibung, requireTwoFactor-Richtlinie oder Berechtigungssatz einer benutzerdefinierten Rolle. |
/api/v1/rbac/roles/:roleId | DELETE | Löscht eine eigene Rolle (schlägt sicher fehl, wenn noch aktive Teammitglieder zugewiesen sind). |
/api/v1/rbac/roles/:roleId/inheritance | GET | Liefert den Eltern-Kind-Vererbungsgraphen für die angegebene Rolle. |
/api/v1/rbac/roles/:roleId/inherited-permissions | GET | Berechnet die effektive Vereinigung aus direkten Berechtigungen und geerbten Berechtigungen übergeordneter Rollen. |
/api/v1/rbac/roles/:roleId/template-access | POST | Bindet die Rolle an eine explizite Positivliste von templateIds (accessMode: 'SCOPED'). |
Benutzerdefinierte Rolle mit Vererbung anlegen
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"
]
}
Antwort-Payload (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"
}
Rolle auf bestimmte Vorlagen beschränken (template-access)
Um eine benutzerdefinierte Rolle so einzugrenzen, dass Mitglieder ausschließlich Pässe bestimmter Vorlagen einsehen und verwalten können:
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"
}
Weiterführende Dokumentation
-
Agenturstrukturen mit mehreren Workspaces verwalten unter Multi-Mandanten-Verwaltung.
-
Persönliche TOTP-2FA konfigurieren unter Profil & Einstellungen.
-
Audit-Protokollexporte prüfen unter Kontosicherheit & Zugriff.
