Multi-Workspace-Hierarchie für Agenturen & Mandantenisolierung
Digitalagenturen, Systemintegratoren und SaaS-Plattformen, die mehrere Händlermarken verwalten, arbeiten innerhalb der zweistufigen Organisationsarchitektur von Passinstance. Eine übergeordnete Organisation (Organization-Modell) fungiert als Dachinstanz für die Governance, die mehrere strikt voneinander isolierte Kunden-Workspaces (Customer-Modell) besitzt und bereitstellt.
Zentrale Isolierungsgrundsätze
-
Strikte Datenpartitionierung: Vorlagen, ausgestellte Karten (
externalId,serialNumber), kryptografische Signaturzertifikate (.p12mit händlerspezifischerbundleId/passTypeIdentifier), Scanner-Validierungsprotokolle, Webhook-Abonnements und personenbezogene Kundendaten (PII) sind strikt auf den jeweiligen Workspace (customerId) begrenzt. -
Keinerlei mandantenübergreifende Datenlecks: Berechtigungsbegrenzte Workspace-API-Schlüssel (
pi_live_undpi_test_) sowie mobile Scannerschlüssel (x-scanner-key) sind kryptografisch an eine einzigecustomerIdgebunden und können niemals Karten eines parallelen Kunden-Workspaces abfragen, verändern oder scannen. -
Kundenspezifische Wallet-Identität: Agenturen laden pro Workspace eigene Apple-Pass-Type-ID-Zertifikate (
bundleId) und Google-Wallet-Ausstellerzugangsdaten hoch, sodass Sperrbildschirm-Benachrichtigungen und Kartenköpfe jedes Händlers dessen eigene Markenidentität anzeigen.
Verwalten von Kunden-Workspaces über die Organisations-API
Agenturadministratoren können über den Organizations API ihre Organisationsstruktur einsehen, neue Kunden-Workspaces bereitstellen, den aktiven Mandantenkontext wechseln und konsolidierte Abrechnungstelemetrie abrufen:
| Endpunktpfad | Methode | Authentifizierung | Beschreibung | ||
|---|---|---|---|---|---|
/api/v1/organizations/current | GET / PUT | Bearer | Liest oder aktualisiert die aktive Organization, Mitgliederrollen (OrganizationMemberRole: `OWNER \ | ADMIN \ | MEMBER) sowie alle zugänglichen parallelen Customer`-Workspaces. |
/api/v1/organizations/current/workspaces | POST | Bearer | Stellt einen neuen isolierten Kunden-Workspace bereit (`kind: "production" \ | "sandbox"`). | |
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Wechselt den aktiven Workspace-Kontext und rotiert die Sitzungs-Authentifizierungs-Tokens. | ||
/api/v1/organizations/current/billing-summary | GET | Bearer | Aggregiert Tarifkontingente und die Anzahl aktiver Wallet-Karten über alle untergeordneten Workspaces hinweg. |
Bereitstellen eines neuen Kunden-Workspaces
Wenn Sie einen neuen Händler einbinden oder eine dedizierte Testumgebung einrichten, rufen Sie POST /api/v1/organizations/current/workspaces mit dem request payload auf (name und kind: ausschließlich "production" oder "sandbox"; konfigurieren Sie anschließend die regionalen Standardwerte separat über PUT /api/v1/customer/:customerId/regional-settings):
{
"name": "Artisan Coffee Roasters — EU",
"kind": "production"
}
Wechseln von Workspaces & Sitzungsrotation
Wenn ein Agenturmitarbeiter im Dashboard oder über POST /api/v1/organizations/current/workspaces/switch zwischen Kundenkonten wechselt, führt Passinstance eine atomare Sitzungsrotation durch, um eine mandantenübergreifende Statusvermischung auszuschließen:
{
"workspaceId": "cust_client_a_01"
}
Antwort (200 OK):
{
"activeWorkspace": {
"id": "cust_client_a_01",
"name": "Artisan Coffee Roasters — EU",
"kind": "production",
"role": "ADMIN"
},
"sessionRotated": true,
"issuedAt": "2026-11-15T14:22:10.000Z"
}
Konsolidierte Abrechnungsübersicht für Agenturen
Anstatt separate Rechnungen für jedes einzelne Kundenprojekt abzustimmen, können Agenturinhaber die kumulierten aktiven Wallet-Installationen über alle Produktions-Workspaces hinweg über GET /api/v1/organizations/current/billing-summary überwachen:
{
"organizationId": "org_agency_8841",
"planTier": "SCALE_10K",
"includedActivePasses": 10000,
"totalActivePassesAcrossWorkspaces": 6420,
"workspaces": [
{
"workspaceId": "cust_client_a_01",
"name": "Artisan Coffee Roasters — EU",
"kind": "production",
"activePasses": 4120
},
{
"workspaceId": "cust_client_b_02",
"name": "Artisan Coffee — Sandbox",
"kind": "sandbox",
"activePasses": 0
}
]
}
Wichtig: Das Feld
kindeines Workspaces akzeptiert gemäßrequest payloadausschließlich"production"oder"sandbox". Sandbox-Workspaces isolieren das Prototyping von Vorlagen und Integrationstests, ohne Kapazitäten für aktive Wallet-Karten aus dem Produktions-Abrechnungskontingent Ihrer Organisation zu verbrauchen.
Sehen Sie sich die vollständigen Multi-Tenant-Funktionen auf der Seite White-Label- & Multi-Tenant-Übersicht an oder entdecken Sie unsere Partnerprogramme für Agenturen unter /partners.
