Multi-Tenancy

Multi-tenancy in HelloJohn means that one HelloJohn instance can serve many independent applications (tenants), each with complete data isolation. This is the foundation for building B2B SaaS platforms.

The tenant model

HelloJohn Instance
└── Tenant (one product / one customer / one environment)
    ├── Client A  (your web app)  → publishable_key: pk_live_...
    ├── Client B  (your mobile app) → publishable_key: pk_live_...
    └── Client C  (your backend) → secret_key: sk_live_...
        └── Users (end users of your app)
            └── Organizations (groups of users within your app)

Tenant — the top-level isolation unit. Maps to one product or one environment.

Client — an OAuth2 application within a tenant. One tenant can have multiple clients (web, mobile, API). Each client has its own key pair.

User — an end user of your application. Users belong to one tenant (their data lives in the tenant's isolated database).

Organization — a group of users within a tenant. Used for B2B SaaS where your users belong to "companies" or "workspaces."

Tenant isolation

Each tenant gets hard database isolation:

No tenant can access another tenant's data — not through the API, not through shared DB queries, not through any SDK method.

When do you need multi-tenancy?

One tenant is enough for:

• A single product with all users in one pool
• A SaaS where all users log in with the same credentials domain
• An internal tool or single-org deployment

Multiple tenants are for:

• Your platform sells to businesses (B2B SaaS) — each customer is a tenant
• You run multiple products and want separate user pools
• You have separate staging/production environments

Organizations (within one tenant) are for:

• Your SaaS users belong to "companies" or "workspaces" within your product
• You need role-based access at the company level
• You want per-org SSO configuration

Using multiple environments as tenants

A common pattern: one tenant per environment.

HelloJohn Instance
├── Tenant: "Acme Production"  (pk_live_...)
├── Tenant: "Acme Staging"     (pk_test_...)
└── Tenant: "Acme Dev"         (pk_dev_...)

This gives you complete data isolation between environments, matching behavior on real user-like data in staging.

B2B SaaS architecture

For B2B SaaS platforms, you typically use a single tenant with Organizations:

Tenant: "Your SaaS Product"
├── Organization: "Customer A" (org_01HABCDEF...)
│   ├── User: alice@customera.com (role: owner)
│   ├── User: bob@customera.com  (role: admin)
│   └── User: charlie@customera.com (role: member)
│
├── Organization: "Customer B" (org_01HABCDEF...)
│   ├── User: david@customerb.com  (role: owner)
│   └── User: eve@customerb.com    (role: member)
│
└── Users without org (personal accounts)

The JWT includes org_id when the user is acting within an organization, enabling your backend to scope data by organization.

Per-tenant configuration

Each tenant can independently configure:

# Configure a tenant via hjctl
hjctl tenant update acme \
  --mfa-policy required \
  --session-duration 8h \
  --allowed-origins "https://app.acme.com"

Tenant routing

HelloJohn routes requests to the correct tenant using the publishable key or secret key in the request. There's no need to pass a tenant ID explicitly — the key identifies the tenant.

# This request goes to Tenant A's Data Plane
POST /v1/auth/sign-in
X-Client-Id: pk_live_TENANT_A_KEY

# This request goes to Tenant B's Data Plane
POST /v1/auth/sign-in
X-Client-Id: pk_live_TENANT_B_KEY

HelloJohn Cloud: managed multi-tenancy ☁️

On HelloJohn Cloud, tenant provisioning is instant and fully managed. You can create tenants via the dashboard, API, or hjctl. Cloud also provides a multi-tenant dashboard on the Pro plan and above — manage all your tenants and their users from one interface.

Next steps

• Organizations →
• Tokens & JWT →
• Control Plane API →
• OSS vs Cloud →