Skip to content
Hilfecenter-Anleitung · Konto- & Workspace-Einstellungen
3 Min. LesezeitGeprüft 2026-11-16

Teammitglieder & Berechtigungen

Laden Sie Teammitglieder ein, vergeben Sie Admin-/Editor-/Operator-Rollen und aktivieren Sie rollenpflichtige 2FA.

In dieser Anleitung

Ü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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
MEHRSTUFIGES RBAC & VORLAGEN-SCOPING
STUFE 01 EBENE 1: ORGANISATIONS-GOVERNANCE
Organization-Rollen: OWNER | ADMIN | MEMBER
Steuert Multi-Workspace-Provisionierung, Sammelabrechnung & SSO/SAML
STUFE 02 EBENE 2: WORKSPACE-ROLLENHIERARCHIE
Team Permissions API (/api/v1/rbac/roles)
Systemrollen: Workspace Admin, Campaign Editor, Scanner Operator
Eigene Rollen: POST/api/v1/rbac/roles mit granularen Berechtigungen
Rollenvererbung: GET/api/v1/rbac/roles/:roleId/inheritance
STUFE 03 EBENE 3: VORLAGENSPEZIFISCHE ZUGRIFFSGRENZEN
POST/api/v1/rbac/roles/:roleId/template-access
Beschränkt Rolleninhaber auf explizite templateId-Positivlisten
Serverseitig durchgesetzt über Pass-Suche, Versand, Scans & Exporte

Wichtig: Autorisierungsprüfungen werden strikt serverseitig in der NestJS-Controller- und Serviceschicht durchgesetzt. Durch die Einschränkung einer benutzerdefinierten Rolle über template-access ist 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 & RolleGeltungsbereichKernfunktionen & Berechtigungen
Organization OWNERAlle Workspaces der OrganisationVollstä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 ADMINZugewiesene / alle WorkspacesVerwaltung von Teameinladungen, Workspace-Einstellungen, Apple-/Google-Signaturzertifikaten, API-Schlüsseln (api:keys-manage) und Webhooks.
Workspace Editor (MEMBER)Einzelner WorkspaceErstellung und Bearbeitung von Pass-Vorlagen, Konfiguration von Mechaniken und Stufen, Ausführung von CSV-Stapelimporten sowie Delivery-Center-Kampagnen.
Workspace OperatorEinzelner Workspace / Freigegebene VorlagenEinzelne 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

EndpunktHTTP-VerbBeschreibung
/api/v1/rbac/rolesGETListet alle System- und benutzerdefinierten Rollen im aktiven Workspace auf.
/api/v1/rbac/rolesPOSTErstellt eine eigene RBAC-Rolle mit expliziten Berechtigungs-Tokens und optionaler Elternrollen-Vererbung.
/api/v1/rbac/roles/:roleIdPUTAktualisiert Namen, Beschreibung, requireTwoFactor-Richtlinie oder Berechtigungssatz einer benutzerdefinierten Rolle.
/api/v1/rbac/roles/:roleIdDELETELöscht eine eigene Rolle (schlägt sicher fehl, wenn noch aktive Teammitglieder zugewiesen sind).
/api/v1/rbac/roles/:roleId/inheritanceGETLiefert den Eltern-Kind-Vererbungsgraphen für die angegebene Rolle.
/api/v1/rbac/roles/:roleId/inherited-permissionsGETBerechnet die effektive Vereinigung aus direkten Berechtigungen und geerbten Berechtigungen übergeordneter Rollen.
/api/v1/rbac/roles/:roleId/template-accessPOSTBindet die Rolle an eine explizite Positivliste von templateIds (accessMode: 'SCOPED').

Benutzerdefinierte Rolle mit Vererbung anlegen

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

Antwort-Payload (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"
}

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:

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

Weiterführende Dokumentation

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.