Skip to content
Guida del Centro assistenza · Agenzie e partner
3 min di letturaVerificato 2026-11-16

Gestione multi-cliente

Gestisci workspace clienti separati con rigoroso isolamento dei dati e chiavi API dedicate per agenzie.

In questa guida

Gerarchia multi-workspace per agenzie e isolamento dei tenant

Le agenzie digitali, i system integrator e le piattaforme SaaS che gestiscono più brand di esercenti operano all'interno dell'architettura organizzativa a due livelli di Passinstance. Un'Organizzazione di primo livello (modello Organization) funge da entità di governance ombrello che possiede e attiva molteplici Workspace Cliente rigorosamente isolati (modello Customer).

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
TENANCY MULTI-WORKSPACE PER AGENZIE
FASE 01 ORGANIZZAZIONE AGENZIA (Modello Organization)
Governance centralizzata (OrganizationMemberRole: OWNER, ADMIN, MEMBER)
Riepilogo fatturazione consolidato (GET/api/v1/organizations/current/billing-summary)
FASE 02 1:N Workspace clienti isolati
WORKSPACE CLIENTE A (production)
ID Tenant: cust_client_a_01
.p12 Apple e Auth Google dedicati
Chiavi con ambito: pi_live_...
Chiavi scanner e webhook separati
WORKSPACE CLIENTE B (sandbox)
ID Tenant: cust_client_b_02
Modelli e pass di test isolati
Chiavi con ambito: pi_test_...
Impatto zero sulle quote produzione

Invarianti fondamentali di isolamento

  • Partizionamento rigoroso dei dati: i modelli, i pass emessi (externalId, serialNumber), i certificati di firma crittografica (.p12 con bundleId / passTypeIdentifier per singolo esercente), i log di convalida dello scanner, le sottoscrizioni webhook e i dati personali (PII) dei clienti sono isolati nel singolo workspace (customerId).
  • Zero perdite di dati cross-tenant: le chiavi API del workspace con ambito limitato (pi_live_ e pi_test_) e le chiavi dello scanner mobile (x-scanner-key) sono vincolate crittograficamente a un singolo customerId e non possono mai interrogare, modificare o scansionare pass appartenenti a un workspace cliente affiliato.
  • Identità del wallet per singolo cliente: le agenzie caricano certificati Apple Pass Type ID dedicati (bundleId) e credenziali di emittente Google Wallet per ciascun workspace, in modo che le notifiche sulla schermata di blocco e le intestazioni dei pass di ogni esercente mostrino esclusivamente la propria identità di brand.

Gestione dei workspace clienti tramite l'API Organization

Gli amministratori dell'agenzia possono ispezionare la struttura della propria organizzazione, attivare nuovi workspace per i clienti, cambiare il contesto del tenant attivo e recuperare la telemetria di fatturazione consolidata tramite Organizations API:

Percorso EndpointMetodoAutenticazioneDescrizione
/api/v1/organizations/currentGET / PUTBearerLegge o aggiorna l'Organization attiva, i ruoli dei membri (OrganizationMemberRole: `OWNERADMINMEMBER) e tutti i workspace Customer` affiliati accessibili.
/api/v1/organizations/current/workspacesPOSTBearerAttiva un nuovo workspace cliente isolato (`kind: "production" \"sandbox"`).
/api/v1/organizations/current/workspaces/switchPOSTBearerCambia il contesto del workspace attivo e ruota i token di autenticazione della sessione.
/api/v1/organizations/current/billing-summaryGETBearerAggrega le quote del piano e il conteggio dei pass attivi nei wallet su tutti i workspace figli.

Attivazione di un nuovo workspace cliente

Quando avvia l'onboarding di un nuovo esercente o configura un ambiente di test dedicato, chiami POST /api/v1/organizations/current/workspaces con request payload (name e kind: rigorosamente "production" o "sandbox", quindi configuri separatamente le impostazioni regionali predefinite tramite PUT /api/v1/customer/:customerId/regional-settings):

JSON
{
  "name": "Artisan Coffee Roasters — EU",
  "kind": "production"
}

Cambio di workspace e rotazione della sessione

Quando un operatore dell'agenzia passa da un account cliente all'altro nella Dashboard o tramite POST /api/v1/organizations/current/workspaces/switch, Passinstance esegue una rotazione atomica della sessione per prevenire qualsiasi contaminazione di stato tra tenant:

JSON
{
  "workspaceId": "cust_client_a_01"
}

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

Riepilogo consolidato della fatturazione per l'agenzia

Invece di riconciliare fatture separate per ogni progetto cliente, i titolari dell'agenzia possono monitorare le installazioni cumulative attive nei wallet su tutti i workspace di produzione tramite 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
    }
  ]
}

Importante: Il parametro kind del workspace accetta esclusivamente "production" o "sandbox", come imposto da request payload. I workspace sandbox isolano la prototipazione dei modelli e i test di integrazione senza consumare capacità di pass attivi dalla quota di fatturazione di produzione della Sua organizzazione.

Esamini tutte le funzionalità multi-tenant nella Panoramica White-Label e Multi-Tenant oppure esplori i percorsi di partnership per le agenzie su /partners.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.