Agency Multi-Workspace Hierarchy & Tenant Isolation
Digital agencies, system integrators, and SaaS platforms managing multiple merchant brands operate within Passinstance's two-tier organizational architecture. A top-level Organization (Organization model) acts as the umbrella governance entity that owns and provisions multiple strictly isolated Customer Workspaces (Customer model).
Core Isolation Invariants
-
Strict Data Partitioning: Templates, issued passes (
externalId,serialNumber), cryptographic signing certificates (.p12with per-merchantbundleId/passTypeIdentifier), scanner validation logs, webhook subscriptions, and customer PII are scoped to the individual workspace (customerId). -
Zero Cross-Tenant Leakage: Scoped workspace API keys (
pi_live_andpi_test_) and mobile scanner keys (x-scanner-key) are cryptographically bound to a singlecustomerIdand can never query, mutate, or scan passes belonging to a sibling client workspace. -
Per-Client Wallet Identity: Agencies upload dedicated Apple Pass Type ID certificates (
bundleId) and Google Wallet Issuer credentials per workspace so every merchant's lock-screen notifications and pass headers display their own brand identity.
Managing Client Workspaces via the Organization API
Agency administrators can inspect their organization structure, provision new client workspaces, switch active tenant contexts, and retrieve consolidated billing telemetry via Organizations API:
| Endpoint Path | Method | Auth | Description | ||
|---|---|---|---|---|---|
/api/v1/organizations/current | GET / PUT | Bearer | Reads or updates the active Organization, member roles (OrganizationMemberRole: `OWNER | ADMIN | MEMBER), and all accessible sibling Customer` workspaces. |
/api/v1/organizations/current/workspaces | POST | Bearer | Provisions a new isolated client workspace (`kind: "production" \ | "sandbox"`). | |
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Switches the active workspace context and rotates session authentication tokens. | ||
/api/v1/organizations/current/billing-summary | GET | Bearer | Aggregates plan quotas and active wallet pass counts across all child workspaces. |
Provisioning a New Client Workspace
When onboarding a new merchant or setting up a dedicated test environment, call POST /api/v1/organizations/current/workspaces with request payload (name and kind: strictly "production" or "sandbox", then configure regional defaults separately via PUT /api/v1/customer/:customerId/regional-settings):
{
"name": "Artisan Coffee Roasters — EU",
"kind": "production"
}
Switching Workspaces & Session Rotation
When an agency operator switches between client accounts in the dashboard or via POST /api/v1/organizations/current/workspaces/switch, Passinstance performs an atomic session rotation to prevent cross-tenant state contamination:
{
"workspaceId": "cust_client_a_01"
}
Response (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"
}
Consolidated Agency Billing Summary
Rather than reconciling separate invoices for every client project, agency owners can monitor cumulative active wallet installations across all production workspaces 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: Workspace
kindstrictly accepts"production"or"sandbox"as enforced byrequest payload. Sandbox workspaces isolate template prototyping and integration testing without consuming active wallet pass capacity from your organization's production billing quota.
Review full multi-tenant capabilities on the White-Label & Multi-Tenant Overview or explore agency partnership tracks at /partners.
