Authentication Overview

HelloJohn handles all authentication methods through a single API. Your backend receives the same JWT regardless of how the user signed in.

Authentication methods

MFA methods

MFA can be required globally, per-tenant, per-org, or per-role:

See MFA →.

How auth flows work

Regardless of method, the auth flow ends the same way:

1. User authenticates (email/password, OAuth, magic link, etc.)
2. HelloJohn validates credentials
3. MFA is checked (if enabled)
4. HelloJohn issues access token (JWT) + refresh token
5. SDK stores tokens
6. Your backend receives the JWT in Authorization header
7. Your backend verifies JWT locally (no call to HelloJohn)

Your backend never needs to call HelloJohn to verify a token — it verifies the JWT signature locally using the JWKS public key. See Token Verification →.

Choosing an auth method

Email + password is the right default for most applications. It works for all user types and requires no third-party dependencies.

OAuth / Social Login reduces friction (no password to remember) and is trusted by users. Add it alongside email/password — don't replace it.

Magic links are good for low-frequency applications (internal tools, dashboards) where users may not remember their password.

API keys are for machine-to-machine use: CLI tools, webhooks, CI/CD pipelines, backend services.

SAML SSO is for enterprise customers who need to use their company's identity provider (Okta, Azure AD, Ping). This is Cloud Enterprise only.

Sessions and tokens

Every successful authentication creates a session and issues two tokens:

• Access token — a short-lived JWT (15 minutes by default) for authorizing API requests
• Refresh token — a long-lived opaque token (30 days by default) for getting new access tokens silently

See Sessions → and Tokens & JWT →.

Security defaults

HelloJohn applies these security measures automatically:

Next steps

• Email + Password →
• OAuth / Social Login →
• Token Verification →
• MFA →