Visual System Diagrams

Authentication Journey Flows

Understand the complete authentication journey with visual diagrams that map every hook, API route, and service interaction. Each flow shows exactly how components work together in production environments.

Complete Flows

Total Steps

100%

Production Ready

Jump to flow:

New in v3.4.4: All template modes now correctly respect src/ directory structure. API routes are automatically placed in the right location based on your project setup.

Authentication Journey

From login to usable tokens in five steps

Live orchestration view

AuthCore Engine

Session minting, policy checks, and lifecycle hooks radiate from this hub to your product surfaces.

NextAuthPrismaCLI

User Intent

End-user initiates login from your product surface.

AuthCore Guardrails

Credential, device, and policy checks run inside the authorization service.

AuthCore Actions

Webhooks and business rules fire to trigger audits, MFA, or downstream automation.

Token Minting

ID & Access tokens include tenant metadata, scopes, and TOTP state.

ID · Access

Application Surface

Your UI consumes the session, renders protected views, and calls APIs.

Flow 1

Adaptive authentication policy

Forms pull tenant policy data and pivot into credentials, magic links, or 2FA without custom glue code.

Step 1

Fetch tenant policy

Call `/api/auth/policy` (optionally with `tenantDomain`) to discover login choices, second factor rules, and approval requirements.

Route: GET /api/auth/policyComponent: AuthFormComponent: LoginForm

Step 2

Render allowed sign-in options

Toggle credentials versus magic link UI so it mirrors `enableMagicLinkLogin` and related policy flags.

Hook: useMagicLinkRuntime config: passwordMinLengthPolicy: enableMagicLinkLogin

Step 3

Escalate to second factor when required

When sign-in returns `SECOND_FACTOR_REQUIRED`, swap the UI to TOTP or email OTP using the provided `channels` payload.

NextAuth credentials providerHook: useLoginPolicy: enforceTwoFactor

Step 4

Follow registration hand-offs

Surface the returned `steps` array so people verify email, enroll MFA, or wait on approval without guesswork.

Hook: useRegisterType: RegistrationStep[]Policy: requireEmailVerification

Step 1

Fetch tenant policy

Call `/api/auth/policy` (optionally with `tenantDomain`) to discover login choices, second factor rules, and approval requirements.

Route: GET /api/auth/policyComponent: AuthFormComponent: LoginForm

Step 3

Escalate to second factor when required

When sign-in returns `SECOND_FACTOR_REQUIRED`, swap the UI to TOTP or email OTP using the provided `channels` payload.

NextAuth credentials providerHook: useLoginPolicy: enforceTwoFactor

Adaptive authentication policy

Forms pull tenant policy data and pivot into credentials, magic links, or 2FA without custom glue code.

Fetch tenant policyRender allowed sign-in optionsEscalate to second factor when requiredFollow registration hand-offs

Step 2

Render allowed sign-in options

Toggle credentials versus magic link UI so it mirrors `enableMagicLinkLogin` and related policy flags.

Hook: useMagicLinkRuntime config: passwordMinLengthPolicy: enableMagicLinkLogin

Step 4

Follow registration hand-offs

Surface the returned `steps` array so people verify email, enroll MFA, or wait on approval without guesswork.

Hook: useRegisterType: RegistrationStep[]Policy: requireEmailVerification

Sample snippet

Component: AuthForm API: Authentication

Flow 2

Passwordless magic link

Email-first sign-in that upgrades the session with a single verified click.

Step 1

Collect email + enqueue magic link

Client UI calls `useMagicLink` to POST `/api/auth/magic-link`, recording an expiring token and metadata.

Hook: useMagicLinkRoute: POST /api/auth/magic-link

Step 2

Template render + provider dispatch

Server injects tenant branding, signs the link, and hands delivery to Nodemailer, Resend, or custom providers.

Mailer: magic-link templateConfig: authcore.config.json › email

Step 3

User clicks link + token validation

Callback endpoint verifies integrity, enforces policy, and clears the single-use token.

Route: GET /api/auth/magic-link/callbackService: magicLink.verifyToken

Step 4

Session creation + redirect

NextAuth mints the session cookie and redirects the visitor to the requested origin.

Service: session.createNextAuth adapter: AuthCoreAdapter

Step 1

Collect email + enqueue magic link

Client UI calls `useMagicLink` to POST `/api/auth/magic-link`, recording an expiring token and metadata.

Hook: useMagicLinkRoute: POST /api/auth/magic-link

Step 3

User clicks link + token validation

Callback endpoint verifies integrity, enforces policy, and clears the single-use token.

Route: GET /api/auth/magic-link/callbackService: magicLink.verifyToken

Passwordless magic link

Email-first sign-in that upgrades the session with a single verified click.

Collect email + enqueue magic linkTemplate render + provider dispatchUser clicks link + token validationSession creation + redirect

Step 2

Template render + provider dispatch

Server injects tenant branding, signs the link, and hands delivery to Nodemailer, Resend, or custom providers.

Mailer: magic-link templateConfig: authcore.config.json › email

Step 4

Session creation + redirect

NextAuth mints the session cookie and redirects the visitor to the requested origin.

Service: session.createNextAuth adapter: AuthCoreAdapter

Sample snippet

Guide: Magic Links Hook: useMagicLink

Flow 3

Tenant invitation flow

Invite, accept, and provision tenant administrators without manual role wiring.

Step 1

Admin issues invite

Tenant admins call `useOrganization().inviteMember` to persist a signed invite token with role metadata.

Hook: useOrganizationRoute: POST /api/tenant/invitations

Step 2

Invitation email delivery

Email template ships tenant branding, expiry, and an `/auth/accept-invite` CTA.

Mailer: tenant-invite templateConfig: nodemailer.js

Step 3

Accept + merge accounts

Accept endpoint verifies the token, creates the member, or merges roles into an existing account.

Route: POST /api/auth/accept-invitePrisma: OrganizationMember table

Step 4

Session upgrade

Refresh the session so `useAuth().isTenantAdmin()` immediately reflects the new role.

Hook: useAuthHelper: isTenantAdmin

Step 1

Admin issues invite

Tenant admins call `useOrganization().inviteMember` to persist a signed invite token with role metadata.

Hook: useOrganizationRoute: POST /api/tenant/invitations

Step 3

Accept + merge accounts

Accept endpoint verifies the token, creates the member, or merges roles into an existing account.

Route: POST /api/auth/accept-invitePrisma: OrganizationMember table

Tenant invitation flow

Invite, accept, and provision tenant administrators without manual role wiring.

Admin issues inviteInvitation email deliveryAccept + merge accountsSession upgrade

Step 2

Invitation email delivery

Email template ships tenant branding, expiry, and an `/auth/accept-invite` CTA.

Mailer: tenant-invite templateConfig: nodemailer.js

Step 4

Session upgrade

Refresh the session so `useAuth().isTenantAdmin()` immediately reflects the new role.

Hook: useAuthHelper: isTenantAdmin

Component: OrganizationSwitcher Guide: Adapters

Flow 4

Recovery + two-factor reset

Recover locked-out accounts and rotate secrets when a device goes missing.

Step 1

User initiates restore

Users hit `/auth/restore` to request a signed restore token after lockout checks.

Page: /auth/restoreRoute: POST /api/auth/restore

Step 2

Verifier challenge

Restore endpoint evaluates backup codes, rate limits, or approvals based on policy flags.

Policy: authcore.config.json › security.restoreHook: useAuditLogs

Step 3

Password & 2FA reset

Successful challenge rotates the password and regenerates TOTP secrets with fresh backup codes.

Service: totp.rotateRoute: POST /api/auth/reset-password

Step 4

Re-seed trusted devices

Revoke device tokens with `useUserDevices().revokeDevice` so every client re-authenticates.

Hook: useUserDevicesRoute: POST /api/user/devices/revoke

Step 1

User initiates restore

Users hit `/auth/restore` to request a signed restore token after lockout checks.

Page: /auth/restoreRoute: POST /api/auth/restore

Step 3

Password & 2FA reset

Successful challenge rotates the password and regenerates TOTP secrets with fresh backup codes.

Service: totp.rotateRoute: POST /api/auth/reset-password

Recovery + two-factor reset

Recover locked-out accounts and rotate secrets when a device goes missing.

User initiates restoreVerifier challengePassword & 2FA resetRe-seed trusted devices

Step 2

Verifier challenge

Restore endpoint evaluates backup codes, rate limits, or approvals based on policy flags.

Policy: authcore.config.json › security.restoreHook: useAuditLogs

Step 4

Re-seed trusted devices

Revoke device tokens with `useUserDevices().revokeDevice` so every client re-authenticates.

Hook: useUserDevicesRoute: POST /api/user/devices/revoke

Guide: Security Configuration Hooks Overview