How HelloJohn Works

HelloJohn is an identity and authentication server. It sits between your application and your users, handling the complex parts of auth: credential storage, token issuance, session management, and MFA.

The auth flow in 60 seconds

When a user signs in to your app:

1. Your app redirects to HelloJohn (or the HelloJohn SDK renders the sign-in UI inline)
2. HelloJohn authenticates the user — checks password, runs MFA, validates social token, etc.
3. HelloJohn issues a JWT — signed with EdDSA, containing the user's ID, email, roles, and any custom claims
4. Your app receives the token — stored in memory or secure storage by the SDK
5. Your frontend sends the token to your backend via the Authorization: Bearer <token> header
6. Your backend verifies the token locally — no round-trip to HelloJohn needed

User  →  Your App  →  HelloJohn  →  JWT
                              ↓
              Your Backend  ←  JWT (verified locally)

Token model

HelloJohn issues short-lived access tokens (JWTs) and long-lived refresh tokens.

The access token is a standard JWT. You can inspect it at jwt.io. It contains:

{
  "sub": "user_01HXYZ...",
  "email": "alice@example.com",
  "name": "Alice",
  "roles": ["member"],
  "org": "org_01HXYZ...",
  "iat": 1714000000,
  "exp": 1714000900
}

Signature algorithm

HelloJohn uses EdDSA (Ed25519) for JWT signing — faster and more compact than RS256, with equivalent security. Your backend fetches the public key from the JWKS endpoint once and caches it:

https://your-hellojohn-instance.com/.well-known/jwks.json

All HelloJohn SDKs handle JWKS fetching, caching, and key rotation automatically.

Tenant isolation

HelloJohn is built multi-tenant from the ground up. Each tenant has:

• Its own user pool
• Its own JWKS (optional per-tenant key rotation)
• Its own OAuth2 client configuration
• Configurable data isolation: shared schema, separate schema, or separate database

HelloJohn Instance
├── Tenant A  →  Database A (or schema A)
├── Tenant B  →  Database B (or schema B)
└── Tenant C  →  shared schema, row-level isolation

This makes HelloJohn suitable for both single-app deployments and B2B SaaS platforms with hundreds of organizations.

Session management

Sessions are stored server-side in HelloJohn (in your configured database). When a user signs out:

1. The refresh token is revoked in the database
2. The SDK clears the in-memory access token
3. Future refresh attempts return 401 Unauthorized

Access tokens remain valid until they expire (default: 15 minutes). For immediate revocation, reduce the access token lifetime or use token introspection.

Components

HelloJohn is composed of:

OSS vs Cloud

Both the open-source and Cloud versions use the same core. The differences are operational:

• OSS: You host the server. You own all data. You manage updates and backups.
• Cloud: HelloJohn hosts and operates the server. You get a dashboard, multi-tenancy, and SLA.

Full comparison →

Next steps

• Core concepts →
• React quickstart →
• Token verification deep dive →
• Self-hosting guide →