Skip to content
Hilfecenter-Anleitung · Agenturen & Partner
2 Min. LesezeitGeprüft 2026-11-16

Mandanten- & Kundenverwaltung

Betreiben Sie strikt getrennte Kunden-Workspaces mit isolierten API-Schlüsseln und zentralem Agentur-Provisioning.

In dieser Anleitung

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.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
MULTI-WORKSPACE-MANDANTENFÄHIGKEIT FÜR AGENTUREN
STUFE 01 AGENTUR-ORGANISATION (Organization-Modell)
Zentrale Agentur-Governance (OrganizationMemberRole: OWNER, ADMIN, MEMBER)
Konsolidierte Abrechnung (GET/api/v1/organizations/current/billing-summary)
STUFE 02 1:N Isolierte Kunden-Workspaces
KUNDEN-WORKSPACE A (production)
Mandanten-ID: cust_client_a_01
Eigenes Apple-.p12 & Google-Auth
Begrenzte Keys: pi_live_...
Separate Scanner-Keys & Webhooks
KUNDEN-WORKSPACE B (sandbox)
Mandanten-ID: cust_client_b_02
Isolierte Testvorlagen & Karten
Begrenzte Keys: pi_test_...
Kein Einfluss auf Produktionslimits

Zentrale Isolierungsgrundsätze

  • Strikte Datenpartitionierung: Vorlagen, ausgestellte Karten (externalId, serialNumber), kryptografische Signaturzertifikate (.p12 mit händlerspezifischer bundleId / 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_ und pi_test_) sowie mobile Scannerschlüssel (x-scanner-key) sind kryptografisch an eine einzige customerId gebunden 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:

EndpunktpfadMethodeAuthentifizierungBeschreibung
/api/v1/organizations/currentGET / PUTBearerLiest oder aktualisiert die aktive Organization, Mitgliederrollen (OrganizationMemberRole: `OWNER \ADMIN \MEMBER) sowie alle zugänglichen parallelen Customer`-Workspaces.
/api/v1/organizations/current/workspacesPOSTBearerStellt einen neuen isolierten Kunden-Workspace bereit (`kind: "production" \"sandbox"`).
/api/v1/organizations/current/workspaces/switchPOSTBearerWechselt den aktiven Workspace-Kontext und rotiert die Sitzungs-Authentifizierungs-Tokens.
/api/v1/organizations/current/billing-summaryGETBearerAggregiert 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):

JSON
{
  "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:

JSON
{
  "workspaceId": "cust_client_a_01"
}

Antwort (200 OK):

JSON
{
  "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:

JSON
{
  "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 kind eines Workspaces akzeptiert gemäß request payload ausschließ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.

Weiterführende Produkt- & Entwicklerdoku

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.