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).
Invarianti fondamentali di isolamento
-
Partizionamento rigoroso dei dati: i modelli, i pass emessi (
externalId,serialNumber), i certificati di firma crittografica (.p12conbundleId/passTypeIdentifierper 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_epi_test_) e le chiavi dello scanner mobile (x-scanner-key) sono vincolate crittograficamente a un singolocustomerIde 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 Endpoint | Metodo | Autenticazione | Descrizione | ||
|---|---|---|---|---|---|
/api/v1/organizations/current | GET / PUT | Bearer | Legge o aggiorna l'Organization attiva, i ruoli dei membri (OrganizationMemberRole: `OWNER | ADMIN | MEMBER) e tutti i workspace Customer` affiliati accessibili. |
/api/v1/organizations/current/workspaces | POST | Bearer | Attiva un nuovo workspace cliente isolato (`kind: "production" \ | "sandbox"`). | |
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Cambia il contesto del workspace attivo e ruota i token di autenticazione della sessione. | ||
/api/v1/organizations/current/billing-summary | GET | Bearer | Aggrega 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):
{
"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:
{
"workspaceId": "cust_client_a_01"
}
Risposta (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"
}
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:
{
"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
kinddel workspace accetta esclusivamente"production"o"sandbox", come imposto darequest 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.
