Glossary
Definitions of key terms used throughout the HelloJohn documentation.
Glossary
A reference of terms used across HelloJohn documentation, organized alphabetically.
A
Access Token
A short-lived JWT (typically 1 hour) issued after successful authentication. Used in the Authorization: Bearer header to authenticate API requests. Cannot be revoked directly — wait for expiry or revoke the associated session.
Audit Log A tamper-evident record of all administrative and user actions within a tenant. Used for compliance, security investigations, and debugging. Includes actor, action, resource, IP address, and timestamp.
B
Backup Codes One-time use codes generated for account recovery when a user cannot access their primary MFA factor. Typically 8–10 codes, each valid for a single use. Should be stored securely by the user.
C
Challenge
A temporary token issued during the MFA flow. After a sign-in attempt triggers MFA, a challenge_id is returned. The client uses this ID to verify the OTP against the correct factor.
Client
A registered application that interacts with HelloJohn (web app, SPA, mobile app, or backend service). Each client has a client_id and optionally a client_secret. See Clients API.
Control Plane (CP) The management layer of HelloJohn responsible for tenant configuration, provisioning, and administrative operations. Hosts the dashboard and the tenants API. Isolated from the Data Plane.
Cursor Pagination
HelloJohn list endpoints use cursor-based pagination instead of page numbers. The response includes a next_cursor value; pass it as the cursor query parameter to fetch the next page.
D
Data Plane (DP) The runtime layer that handles authentication requests, token issuance, and user data. Each tenant's Data Plane is isolated. Scales independently from the Control Plane.
E
EdDSA The digital signature algorithm (Ed25519) used to sign HelloJohn JWTs. Preferred over RS256 for performance and security. Public keys are available at the tenant's JWKS endpoint.
F
Factor An MFA method enrolled by a user. Supported factors: TOTP (authenticator app), SMS OTP, email OTP, WebAuthn (hardware keys / passkeys), and backup codes.
G
Grant Type
The OAuth 2.0 mechanism used to obtain tokens. HelloJohn supports authorization_code (with PKCE), refresh_token, and client_credentials (for machine-to-machine).
I
Idempotency Key
A client-generated UUID passed in the Idempotency-Key header for POST requests. Ensures that retrying a failed request doesn't create duplicate resources. Valid for 24 hours.
Impersonation An admin capability that allows generating an access token for a user without their credentials. All impersonation events are recorded in the audit log.
Invitation An email sent to a user inviting them to join an organization. Contains a time-limited token. When accepted, the user is added as a member with the specified role.
J
JWKS (JSON Web Key Set)
A public endpoint (/.well-known/jwks.json) that exposes the cryptographic public keys used to sign JWTs. Backends use this to verify access tokens locally without calling the HelloJohn API.
JWT (JSON Web Token)
The format used for HelloJohn access tokens. Contains claims like sub (user ID), tenant_id, org_id, role, and mfa_verified. Signed with EdDSA.
M
Magic Link A passwordless authentication method. The user enters their email, receives a unique link, and clicking it creates a session. Links are single-use and expire (default: 15 minutes).
Member
A user who belongs to an organization. Members have a role (owner, admin, or member) within that organization, separate from their system-level role.
MFA (Multi-Factor Authentication) Requiring a second proof of identity in addition to a password or magic link. HelloJohn supports TOTP, SMS OTP, email OTP, WebAuthn, and backup codes.
Multi-tenancy HelloJohn's architecture where multiple customers (tenants) share the same infrastructure but are completely isolated from each other at the data and API level.
O
OAuth 2.0 The authorization framework used by HelloJohn for social login (Google, GitHub, etc.) and SSO. HelloJohn implements the Authorization Code flow with PKCE.
OIDC (OpenID Connect)
An identity layer on top of OAuth 2.0. HelloJohn is OIDC-compliant, exposing a discovery endpoint at /.well-known/openid-configuration.
Organization A group of users within a tenant. Organizations have their own roles, metadata, and settings. A user can belong to multiple organizations.
P
Passkey A WebAuthn credential stored on the user's device or password manager. Allows passwordless, phishing-resistant authentication using biometrics or a hardware key.
PKCE (Proof Key for Code Exchange)
A security extension to OAuth 2.0 that protects the authorization code exchange. Required for public clients (SPAs, native apps). HelloJohn requires S256 code challenge method.
Publishable Key
An API key prefixed with pk_live_ (or pk_test_) that is safe to expose in frontend code. Can only perform client-side operations like initiating sign-in flows.
R
Refresh Token A long-lived token (default: 30 days) used to obtain new access tokens without re-authentication. Stored securely server-side or in an HttpOnly cookie.
Role A label that controls what a user can do. System roles apply tenant-wide; organization roles apply within an organization. Roles are included in the JWT claims.
S
Secret Key
An API key prefixed with sk_live_ (or sk_test_) for server-side use only. Has full access to the API. Never expose in client-side code.
Session An authenticated period for a user, created at sign-in and tied to one access token and one refresh token. Sessions can be listed, inspected, and revoked via the API.
Signing Secret
A secret used to verify webhook payloads. Included in the HelloJohn-Signature header of each webhook delivery. Shown only once at webhook creation.
Slug
A URL-safe, human-readable identifier. For example, an organization named "Acme Corp" might have the slug acme-corp. Used in URLs and as an alternative to IDs.
SSO (Single Sign-On) Enterprise authentication where users sign in through their organization's identity provider (IdP) using SAML 2.0 or OIDC. Configured per tenant or per organization.
T
Tenant The top-level isolation unit in HelloJohn. Each tenant has its own users, organizations, API keys, and configuration. Corresponds to one customer in a multi-tenant SaaS product.
TOTP (Time-based One-Time Password) An MFA method where a 6-digit code is generated by an authenticator app (like Authy or Google Authenticator) and changes every 30 seconds. Based on RFC 6238.
U
User An authenticated identity within a tenant. Users have email, name, metadata, sessions, and optionally MFA factors. Can belong to multiple organizations.
W
WebAuthn A W3C standard for hardware-key and passkey authentication. Supported by HelloJohn as an MFA factor and as a primary passwordless method.
Webhook An HTTP POST notification sent from HelloJohn to your server when specific events occur (e.g., user created, session revoked). Payloads are signed with HMAC-SHA256.