Skip to content
Guide du centre d'aide · Agences & partenaires
3 min de lectureVérifié 2026-11-16

Gestion multi-clients

Opérez des espaces clients cloisonnés avec isolation stricte des données, clés dédiées et déploiement agence.

Dans ce guide

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).

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : ARCHITECTURE MULTI-ESPACES DE TRAVAIL AGENCE
ÉTAPE 01 ORGANISATION AGENCE (Modèle Organization)
Gouvernance centralisée (OrganizationMemberRole : OWNER, ADMIN, MEMBER)
Cumul de facturation (GET/api/v1/organizations/current/billing-summary)
ÉTAPE 02 1:N Espaces de travail clients isolés
ESPACE CLIENT A (production)
ID locataire : cust_client_a_01
Certificat Apple .p12 & Google Auth
Clés ciblées : pi_live_...
Clés scanner et webhooks séparés
ESPACE CLIENT B (sandbox)
ID locataire : cust_client_b_02
Modèles et passes de test isolés
Clés ciblées : pi_test_...
Aucun impact sur les quotas de prod

Invariants fondamentaux d'isolation

  • Cloisonnement strict des données : Les modèles, les passes émis (externalId, serialNumber), les certificats de signature cryptographique (.p12 avec bundleId / passTypeIdentifier propre à 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_ et pi_test_) ainsi que les clés de scanner mobile (x-scanner-key) sont liées cryptographiquement à un seul customerId et 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 terminaisonMéthodeAuthDescription
/api/v1/organizations/currentGET / PUTBearerLit ou met à jour l'entité Organization active, les rôles des membres (OrganizationMemberRole : `OWNERADMINMEMBER) et tous les espaces de travail Customer` affiliés accessibles.
/api/v1/organizations/current/workspacesPOSTBearerProvisionne un nouvel espace de travail client isolé (`kind: "production" \"sandbox"`).
/api/v1/organizations/current/workspaces/switchPOSTBearerBascule le contexte d'espace de travail actif et effectue une rotation des jetons d'authentification de session.
/api/v1/organizations/current/billing-summaryGETBearerAgrè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) :

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

JSON
{
  "workspaceId": "cust_client_a_01"
}

Réponse (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"
}

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 :

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

Important : Le champ kind de l'espace de travail accepte strictement "production" ou "sandbox", tel qu'appliqué par request 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.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.