Authentication API

Endpoints and signed callbacks that power AuthCore registration, credential login, passwordless flows, account recovery, and two-factor enforcement.

Public endpoints use the authRoute middleware which rate limits (5 requests per 15 minutes per IP) and records audit logs. Private endpoints require a signed NextAuth session and are wrapped with protectedRoute.

Discover tenant policy

Resolve which login options, MFA requirements, and approval rules apply before rendering any form.

GET/api/auth/policy?tenantDomain=acme
json

When multi-tenancy is enabled, pass either the tenant domain or slug. The response mirrors buildAuthFlowPolicy so UI and server logic stay aligned.

Register

Creates a new user, enforces password policy, and returns the follow-up steps the UI should surface.

POST/api/auth/register
Request
Response
  • Soft-deleted accounts within the retention window return USER_SOFT_DELETED so you can direct the user to the restore flow.
  • Every successful registration includes a steps array. Render each step instead of assuming success.

Credential login + preflight

Use the lightweight preflight endpoint to determine if a TOTP prompt is required before calling NextAuth.

POST/api/auth/check-2fa
Request
Response

If requires2FA is true, prompt for TOTP or email OTP before continuing.

Actual credential login is handled by NextAuth's credentials provider located at /api/auth/[...nextauth]:

tsx

Passwordless magic links

Queue email magic links and handle single-use token redemption.

POST/api/auth/magic-link
Request
Response

The mailer injects tenant branding and signs the callback URL automatically.

GET/api/auth/verify?token=...

Clicking the link verifies the token, mints the NextAuth session cookie, and redirects to /demo/dashboard by default.

Email verification & approvals

POST/api/auth/verify-email
Request

Marks emailVerified and deletes the verification token.

POST/api/auth/resend-verification
Request

Returns 200 even if the user is already verified to avoid enumeration.

Password reset

Two endpoints cover the request/consume lifecycle and never leak whether an account exists.

POST/api/auth/forgot-password
Request
Response
POST/api/auth/reset-password
Request

Account restore (soft-deleted users)

Restore requests respect the configured retention window and never reveal if an account was deleted.

POST/api/auth/restore-request
Request
POST/api/auth/restore
Request

Two-factor lifecycle

All two-factor routes require an authenticated session via protectedRoute.

GET/api/auth/2fa/setup
Status response
POST/api/auth/2fa/setup
Setup response
POST/api/auth/2fa/verify
Request
POST/api/auth/2fa/disable
Request
POST/api/auth/2fa/backup-codes
Request

Backup codes and disable flows require a current TOTP token to prevent hijacking.

Related resources

AuthForm component →

See how the modal form wires these endpoints together.

React hooks →

Review useAuthPolicy, useLogin, and friends.