Core Concepts

This page defines the core entities and concepts in HelloJohn. Understanding these terms will make the rest of the documentation much clearer.

Users

A user is an identity record in HelloJohn. Each user has:

• A unique ID (user_01HXYZ...)
• At least one credential (password, passkey, or social account)
• Profile fields: email, name, avatar, phone (all optional except email)
• Metadata: publicMetadata (readable by the frontend) and privateMetadata (server-only)
• A createdAt timestamp and lastSignInAt

Users belong to exactly one instance but can be members of multiple organizations.

Instances

An instance is one running HelloJohn server. In OSS, you deploy one instance. In Cloud, HelloJohn manages the instance for you.

An instance has:

• A unique domain (e.g., auth.myapp.com or myapp.hellojohn.dev)
• One or more OAuth2 clients (your apps that connect to it)
• Global settings: allowed social providers, MFA policy, password policy

Tenants

In multi-tenant deployments, a tenant is an isolated user pool within your instance. Each tenant:

• Has its own user records
• Can have its own OAuth2 client configuration
• Can use separate database schemas or separate databases entirely

Tenants map to organizations when using HelloJohn's organizations feature.

Sessions

A session represents an authenticated user on a specific device. When a user signs in:

1. A session is created in HelloJohn's database
2. The SDK receives an access token + refresh token
3. The access token is used for API calls; the refresh token renews it

Sessions can be:

• Active — the user is signed in
• Revoked — the user signed out or an admin invalidated the session
• Expired — the session lifetime elapsed without a refresh

You can list and revoke sessions via the Admin API or hjctl.

Tokens

Access Token

A short-lived JWT (JSON Web Token) signed with EdDSA (Ed25519). Contains the user's identity claims. Valid for 15 minutes by default.

Your backend verifies it locally using the public key from JWKS — no API call required.

{
  "sub": "user_01HXYZ...",
  "email": "alice@example.com",
  "roles": ["admin"],
  "org": "org_01HXYZ...",
  "exp": 1714000900
}

Refresh Token

An opaque, long-lived token stored in the SDK's secure storage. Used to silently obtain new access tokens. Never sent to your backend. Valid for 30 days by default.

Publishable Key

A public key prefixed with pk_.... Safe to include in client-side code. Identifies your app to HelloJohn.

Secret Key

A private key prefixed with sk_.... Never expose this in client-side code. Used by your backend to call the HelloJohn Admin API and verify tokens with additional context.

Organizations

An organization is a group of users within your app — typically a company, team, or workspace in a B2B product.

• Users can belong to multiple organizations
• Each membership has a role (e.g., owner, admin, member)
• Organizations can have their own settings: custom domains, SSO configuration, etc.
• Organization context is included in the JWT as the org claim

Organizations are the foundation of multi-tenant SaaS with HelloJohn.

Roles and Permissions

HelloJohn uses RBAC (Role-Based Access Control).

• Roles are assigned per-user (globally) or per-organization-membership
• Permissions are defined in your HelloJohn configuration and assigned to roles
• Roles and permissions appear in the JWT as claims (roles, permissions)

Custom claims can be added using CEL expressions that run at token issuance time.

OAuth2 Clients

An OAuth2 client represents one of your applications. Each client has:

• A Client ID and Client Secret
• A Publishable Key for frontend code
• Allowed redirect URIs
• Configurable token lifetimes and scopes

You create clients in the HelloJohn Dashboard (Cloud) or via hjctl clients create (OSS).

Social Providers

HelloJohn supports 9 built-in social login providers: Google, GitHub, Apple, Microsoft, Discord, Slack, Twitter/X, Facebook, and LinkedIn.

When a user signs in with a social provider:

1. HelloJohn handles the OAuth2 flow
2. The provider's identity is linked to the HelloJohn user record
3. A standard HelloJohn JWT is issued — your backend sees the same token shape regardless of provider

MFA (Multi-Factor Authentication)

HelloJohn supports multiple second factors:

MFA policy can be set to: optional, required, or per-organization.

Webhooks

HelloJohn emits webhook events for 36 audit-worthy actions:

• User events: user.created, user.updated, user.deleted, user.signed_in, user.signed_out
• Session events: session.created, session.revoked
• Organization events: org.member.added, org.member.removed, org.role.changed
• MFA events: mfa.factor.added, mfa.challenge.succeeded, mfa.challenge.failed

Webhooks are delivered with HMAC-SHA256 signatures and retried with exponential backoff on failure.

MCP Server

HelloJohn includes a built-in MCP (Model Context Protocol) server with 46 tools for AI agent control. AI agents can:

• Create and manage users, sessions, and organizations
• Issue tokens, revoke sessions, update roles
• Run migrations and manage tenants

The MCP server is available via stdio and SSE transports.

Next steps

• How HelloJohn works →
• OSS vs Cloud →
• React quickstart →
• Organizations deep dive →