HelloJohn's Data Plane handles authentication, sessions, and user data for each tenant. Learn about per-tenant database isolation and the auth request lifecycle.

The Data Plane is the auth layer that your users interact with. It handles every authentication action — sign-in, token issuance, MFA, session refresh — and stores user data in an isolated per-tenant database.

What the Data Plane handles

User registration and authentication (email/password, OAuth, MFA)
JWT issuance (access tokens) and refresh token management
Session tracking and revocation
Organizations, memberships, and roles
User profiles and metadata
Webhooks for auth events

Per-tenant database isolation

Every tenant gets its own isolated database (or schema). This is a hard architectural boundary — not just row-level security.

HelloJohn Instance
├── Global DB (Control Plane)
│   ├── cp_tenant       ← all tenants
│   ├── cp_client       ← all clients
│   └── cp_admin        ← all CP admins
│
├── Tenant A DB         ← only Tenant A data
│   ├── hj_user
│   ├── hj_session
│   ├── hj_mfa_factor
│   └── hj_organization
│
└── Tenant B DB         ← only Tenant B data
    ├── hj_user
    ├── hj_session
    └── ...

Why per-tenant DB instead of row-level security (RLS)?

	Per-Tenant DB	Row-Level Security
Isolation guarantee	Hard (schema-level)	Soft (policy misconfiguration possible)
Data residency	Configurable per tenant	Same cluster
Performance	No cross-tenant query overhead	Shared query plan cache
Backup granularity	Per-tenant backup/restore	All-tenants only
Compliance	Easier to certify	Requires audit of RLS policies

On OSS with many tenants, you can choose between separate_database, separate_schema, or shared_schema isolation modes. Configure with HELLOJOHN_TENANT_ISOLATION_MODE.

Isolation modes

Mode	Description	Use case
`separate_database`	Each tenant gets its own PostgreSQL database	Strictest isolation, max tenants ~100s
`separate_schema`	Each tenant gets its own schema in a shared database	Good balance, max tenants ~1000s
`shared_schema`	All tenants share tables, isolated by `tenant_id` column	RLS-based, max tenants unlimited

Data Plane API

All auth requests use the Data Plane API. The base URL format is:

https://your-instance.com/v1/

Every Data Plane request requires your publishable key (for client-side) or secret key (for server-side):

# Client-side: use publishable key
POST /v1/auth/sign-in
X-Client-Id: pk_live_XXXXXXXXXXXXXXXX

# Server-side: use secret key (for admin operations)
GET /v1/users
Authorization: Bearer sk_live_XXXXXXXXXXXXXXXX

DAL (Data Abstraction Layer)

HelloJohn's DAL supports multiple database backends:

Backend	Status	Notes
PostgreSQL	✅ Production	Recommended
MySQL / MariaDB	✅ Production	Supported
Filesystem	✅ Dev/Testing	Not for production

The DAL runs embedded migrations on startup. No manual schema setup required.

Auth request lifecycle

Client                SDK               HelloJohn          Your Backend
  │                    │                    │                    │
  │──── sign in ───────►                    │                    │
  │                    │──── POST /v1/auth/sign-in ──────────────►
  │                    │                    │ validate credentials│
  │                    │                    │ check MFA           │
  │                    │◄─── access_token + refresh_token ───────│
  │◄─── session ───────│                    │                    │
  │                    │                    │                    │
  │──── API call ──────►                    │                    │
  │                    │──── GET /your-api (Bearer token) ───────►
  │                    │                    │ verify JWT locally  │
  │                    │                    │ (no call to HelloJohn)
  │◄─── response ──────────────────────────────────────────────┤

JWT verification in your backend requires no network call to HelloJohn — you verify locally using the cached JWKS public key.

Session storage

Sessions are stored server-side in the tenant database. This means:

Logout is immediate and server-authoritative
Sessions are visible to admins
You can list and revoke sessions per device
Session data survives SDK upgrades (stateless client)

Access tokens (JWTs) remain valid until expiration even after logout. Default expiry is 15 minutes. For immediate revocation, reduce access token lifetime or use token introspection.

Data Plane