Hiérarchie multi-espaces de travail pour agences et isolation des locataires
Les agences digitales, les intégrateurs système et les plateformes SaaS qui gèrent plusieurs marques commerçantes opèrent au sein de l'architecture organisationnelle à deux niveaux de Passinstance. Une Organisation de premier niveau (modèle Organization) agit comme l'entité de gouvernance chapeau qui possède et provisionne plusieurs espaces de travail clients strictement isolés (modèle Customer).
Invariants fondamentaux d'isolation
-
Cloisonnement strict des données : Les modèles, les passes émis (
externalId,serialNumber), les certificats de signature cryptographique (.p12avecbundleId/passTypeIdentifierpropre à chaque commerçant), les journaux de validation du scanner, les abonnements aux webhooks et les données personnelles (PII) des clients sont rattachés à l'espace de travail individuel (customerId). -
Zéro fuite inter-locataires : Les clés API d'espace de travail ciblées (
pi_live_etpi_test_) ainsi que les clés de scanner mobile (x-scanner-key) sont liées cryptographiquement à un seulcustomerIdet ne peuvent jamais interroger, modifier ou scanner des passes appartenant à un espace de travail client affilié. -
Identité de portefeuille par client : Les agences téléversent des certificats Apple Pass Type ID dédiés (
bundleId) et des identifiants d'émetteur Google Wallet par espace de travail afin que les notifications sur l'écran verrouillé et les en-têtes de passes de chaque commerçant affichent leur propre identité de marque.
Gestion des espaces de travail clients via l'API Organization
Les administrateurs d'agence peuvent inspecter la structure de leur organisation, provisionner de nouveaux espaces de travail clients, basculer entre les contextes de locataires actifs et récupérer la télémétrie de facturation consolidée via Organizations API :
| Chemin du point de terminaison | Méthode | Auth | Description | ||
|---|---|---|---|---|---|
/api/v1/organizations/current | GET / PUT | Bearer | Lit ou met à jour l'entité Organization active, les rôles des membres (OrganizationMemberRole : `OWNER | ADMIN | MEMBER) et tous les espaces de travail Customer` affiliés accessibles. |
/api/v1/organizations/current/workspaces | POST | Bearer | Provisionne un nouvel espace de travail client isolé (`kind: "production" \ | "sandbox"`). | |
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Bascule le contexte d'espace de travail actif et effectue une rotation des jetons d'authentification de session. | ||
/api/v1/organizations/current/billing-summary | GET | Bearer | Agrège les quotas de forfaits et les compteurs de passes de portefeuille actifs sur l'ensemble des espaces de travail enfants. |
Provisionnement d'un nouvel espace de travail client
Lors de l'intégration d'un nouveau commerçant ou de la configuration d'un environnement de test dédié, appelez POST /api/v1/organizations/current/workspaces avec request payload (name et kind : strictement "production" ou "sandbox", puis configurez les paramètres régionaux par défaut séparément via PUT /api/v1/customer/:customerId/regional-settings) :
{
"name": "Artisan Coffee Roasters — EU",
"kind": "production"
}
Changement d'espace de travail et rotation de session
Lorsqu'un opérateur d'agence bascule entre des comptes clients dans le tableau de bord ou via POST /api/v1/organizations/current/workspaces/switch, Passinstance effectue une rotation atomique de session afin d'éviter toute contamination d'état inter-locataires :
{
"workspaceId": "cust_client_a_01"
}
Réponse (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"
}
Résumé de facturation consolidé pour les agences
Plutôt que de rapprocher des factures distinctes pour chaque projet client, les propriétaires d'agence peuvent suivre le cumul des installations actives dans les portefeuilles sur l'ensemble des espaces de travail de production via GET /api/v1/organizations/current/billing-summary :
{
"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
}
]
}
Important : Le champ
kindde l'espace de travail accepte strictement"production"ou"sandbox", tel qu'appliqué parrequest payload. Les espaces de travail sandbox isolent le prototypage de modèles et les tests d'intégration sans consommer la capacité de passes de portefeuille actifs du quota de facturation de production de votre organisation.
Consultez l'ensemble des fonctionnalités multi-locataires sur la page Présentation de l'API en marque blanche et multi-locataires ou découvrez nos parcours de partenariat pour les agences sur /partners.
