Skip to content
Help Center Guide · Agencies & Partners
3 min readVerified 2026-11-16

Multi-Client Management

Operate isolated client workspaces with strict tenant separation, scoped API keys, and centralized agency provisioning.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
AGENCY MULTI-WORKSPACE TENANCY
STAGE 01 AGENCY ORGANIZATION (Organization Model)
Centralized Agency Governance (OrganizationMemberRole: OWNER, ADMIN, MEMBER)
Consolidated Billing Rollup (GET/api/v1/organizations/current/billing-summary)
STAGE 02 1:N Isolated Client Workspaces
CLIENT A WORKSPACE (production)
Tenant ID: cust_client_a_01
Dedicated Apple .p12 & Google Auth
Scoped Keys: pi_live_...
Separate Scanner Keys & Webhooks
CLIENT B WORKSPACE (sandbox)
Tenant ID: cust_client_b_02
Isolated Test Templates & Passes
Scoped Keys: pi_test_...
Zero Impact on Production Quotas

Core Isolation Invariants

  • Strict Data Partitioning: Templates, issued passes (externalId, serialNumber), cryptographic signing certificates (.p12 with per-merchant bundleId / 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_ and pi_test_) and mobile scanner keys (x-scanner-key) are cryptographically bound to a single customerId and 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 PathMethodAuthDescription
/api/v1/organizations/currentGET / PUTBearerReads or updates the active Organization, member roles (OrganizationMemberRole: `OWNERADMINMEMBER), and all accessible sibling Customer` workspaces.
/api/v1/organizations/current/workspacesPOSTBearerProvisions a new isolated client workspace (`kind: "production" \"sandbox"`).
/api/v1/organizations/current/workspaces/switchPOSTBearerSwitches the active workspace context and rotates session authentication tokens.
/api/v1/organizations/current/billing-summaryGETBearerAggregates 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):

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

JSON
{
  "workspaceId": "cust_client_a_01"
}

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

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:

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: Workspace kind strictly accepts "production" or "sandbox" as enforced by request 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.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.