1Step 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
System diagrams
Authentication & recovery journeys
Each diagram maps the AuthCore hooks, APIs, and services you stitch together in production. Zoom in on the authentication journey below, then explore additional flows for passwordless access, tenant onboarding, and recovery.
Authentication Journey
From login to usable tokens in five steps
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 · AccessApplication 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.
2Step 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
3Step 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
4Step 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
Flow 2
Passwordless magic link
Email-first sign-in that upgrades the session with a single verified click.
1Step 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
2Step 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
3Step 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
4Step 4
Session creation + redirect
NextAuth mints the session cookie and redirects the visitor to the requested origin.
Service: session.createNextAuth adapter: AuthCoreAdapter
Sample snippet
Flow 3
Tenant invitation flow
Invite, accept, and provision tenant administrators without manual role wiring.
1Step 1
Admin issues invite
Tenant admins call `useOrganization().inviteMember` to persist a signed invite token with role metadata.
Hook: useOrganizationRoute: POST /api/tenant/invitations
2Step 2
Invitation email delivery
Email template ships tenant branding, expiry, and an `/auth/accept-invite` CTA.
Mailer: tenant-invite templateConfig: nodemailer.js
3Step 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
4Step 4
Session upgrade
Refresh the session so `useAuth().isTenantAdmin()` immediately reflects the new role.
Hook: useAuthHelper: isTenantAdmin
Flow 4
Recovery + two-factor reset
Recover locked-out accounts and rotate secrets when a device goes missing.
1Step 1
User initiates restore
Users hit `/auth/restore` to request a signed restore token after lockout checks.
Page: /auth/restoreRoute: POST /api/auth/restore
2Step 2
Verifier challenge
Restore endpoint evaluates backup codes, rate limits, or approvals based on policy flags.
Policy: authcore.config.json › security.restoreHook: useAuditLogs
3Step 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
4Step 4
Re-seed trusted devices
Revoke device tokens with `useUserDevices().revokeDevice` so every client re-authenticates.
Hook: useUserDevicesRoute: POST /api/user/devices/revoke