Routes Reference

The IAM service registers 26 HTTP endpoints across six express.Router instances plus two standalone endpoints. When using bootstrapApp(), all routes are mounted automatically in the correct order. When building a custom Express app, mount each router with app.use().

import express from 'express'
import cookieParser from 'cookie-parser'
import {
  authenticationRoutes,
  tokenRotationRoutes,
  magicLinks,
  bffAccessRoute,
  apiVerificationRoute,
  apiProtectedRoutes,
  sendOperationalConfig,
} from '@riavzon/auth'

const app = express()

app.use(apiVerificationRoute())
app.use(cookieParser())
app.use(authenticationRoutes)
app.use(tokenRotationRoutes)
app.use(magicLinks)
app.use(bffAccessRoute)
app.use(apiProtectedRoutes())
app.use('/operational/config', sendOperationalConfig)

For the full middleware stack applied by bootstrapApp(), see the Middleware Reference.

authenticationRoutes

Core signup, login, and OAuth entry points. Every route in this router enforces Content-Type: application/json, rejects empty request bodies, and requires the canary_id cookie.

POST /signup

Registers a new user account with email and password. Validates the request body against the signup Zod schema, checks for disposable email providers, verifies the domain's MX record, hashes the password with Argon2id, and creates the user record. On success, issues an access token and a refresh token.

Middleware chain

Request body

Responses

See Signup for the full signup flow documentation.

POST /login

Authenticates a user with email and password. Verifies the password against the stored Argon2id hash, runs rate limiting with consecutive failure tracking, and issues tokens on success.

Middleware chain

Request body

Responses

See Login for the full login flow documentation.

POST /auth/OAuth/:providerName

Authenticates a user via a configured OAuth provider. The :providerName parameter must match a provider registered with configureOauthProviders(). Validates the provider profile against the provider's Zod schema.

Middleware chain

URL parameters

Responses

See OAuth for the full OAuth flow documentation.

tokenRotationRoutes

Manages the access token and refresh token lifecycle after initial authentication. Both routes in this router operate exclusively through cookies. They do not accept request bodies, query strings, or Content-Type headers.

POST /auth/user/refresh-session

Consumes the current refresh token and issues a new access token and refresh token pair. Validates the session against the canary_id cookie, runs the anomaly detection pipeline, checks the session lifetime against MAX_SESSION_LIFE, and revokes the old refresh token before issuing fresh credentials.

Middleware chain

Cookies required

Responses

See Refresh Tokens for the full rotation flow documentation.

POST /auth/logout

Revokes the current refresh token and clears the session cookies. Requires both the access token (in the Authorization header) and the refresh token (in the session cookie).

Middleware chain

Cookies required

Headers required

Responses

See Logout for the full logout flow.

magicLinks

Handles MFA verification, custom MFA flows, email update, and password reset. Every POST route enforces Content-Type: application/json and rejects empty bodies. GET routes read the magic link token from query parameters.

GET /auth/verify-mfa

Previews an MFA magic link. Validates the signed token from the query parameters and returns the link metadata. Limited to a configurable number of GET previews before the link expires.

Middleware chain

Query parameters

Responses

POST /auth/verify-mfa

Submits the MFA code to complete authentication. Consumes the magic link (single-use) and verifies the OTP code. On success, issues new access and refresh tokens.

Middleware chain

Request body

Responses

See MFA for the full adaptive MFA flow.

POST /custom/mfa/:reason

Initiates a custom MFA flow for a sensitive action. Generates a temporary magic link and OTP code, sends the email to the authenticated user, and returns flow metadata. The :reason parameter identifies the action being protected (for example, PAYMENT_CONFIRM, ACCOUNT_DELETE).

Middleware chain

URL parameters

Headers required

Cookies required

Responses

See Magic Links for the full custom MFA flow documentation.

GET /auth/verify-custom-mfa

Previews a custom MFA magic link. Validates the token and returns the link metadata. Requires full authentication.

Middleware chain

Query parameters

POST /auth/verify-custom-mfa

Submits the custom MFA code to complete a protected action. Requires full authentication plus magic link verification.

Middleware chain

Request body

Responses

POST /update/email

Requests an email address change. Requires full authentication plus custom MFA verification. The new email is validated and the change is applied after MFA verification completes.

Middleware chain

Request body

Responses

POST /auth/forgot-password

Initiates a password reset flow by sending a magic link email to the provided address. Does not require authentication. Uses timing normalization to prevent email enumeration.

Middleware chain

Request body

Responses

See Password Reset for the full flow.

GET /auth/reset-password

Previews a password reset magic link. Validates the signed token from the query parameters and returns link metadata.

Middleware chain

Query parameters

Same as the MFA GET routes: token, random, reason, visitor.

Responses

POST /auth/reset-password

Submits the new password to complete the reset flow. Validates the magic link token, checks the new password against the Zod schema and the Have I Been Pwned breach database, hashes it with Argon2id, and updates the user record.

Middleware chain

Request body

Responses

bffAccessRoute

Backend-for-Frontend authorization endpoints. These routes verify the current session and return user data or token metadata to the BFF layer. Both routes require full authentication.

GET /secret/data

Returns authenticated user data to the BFF layer. Verifies that the user and visitor exist in the database and responds with an authorization status.

Middleware chain

Responses

GET /secret/accesstoken/metadata

Returns the decoded access token payload with TTL information. Useful for the BFF layer to check token freshness and determine when to trigger a rotation.

Middleware chain

Responses

The refreshThreshold field indicates 25% of the access token TTL in milliseconds, and shouldRotate is true when the remaining lifetime (msUntilExp) falls below that threshold. The BFF client uses these fields to proactively refresh tokens before they expire.

apiVerificationRoute()

This factory returns the public API-token verification router. In bootstrapApp(), the service mounts it before express.json(), cookieParser(), and the bot-detector middleware because it only reads headers, query parameters, and the resolved client IP.

GET /api/public/verify

Verifies a raw API token against the requested privilege without requiring a user session. The route reads the token from the x-api-key header and the required privilege from the privilege query parameter.

Route-level middleware

This endpoint has no route-level middleware. It goes straight to verifyApiTokenController, so only the service-wide guards from bootstrapApp() apply.

Headers required

Query parameters

Responses

See Verifying Tokens for the full verification flow and response shapes.

apiProtectedRoutes()

This factory returns the authenticated API-token management router. It exposes a shared POST /api/manage/:action pipeline for mutating token actions and a shared GET /api/manage/:action pipeline for token listing.

POST /api/manage/:action

Handles token creation and the manager-backed token actions. Supported :action values are new-token, revoke, metadata, rotate, ip-restriction-update, and privilege-update.

Middleware chain

Supported actions

GET /api/manage/:action

This route currently exposes the listing branch only. The built-in supported value is list-metadata, which returns the current valid token inventory for the authenticated user.

Middleware chain

Supported action

Standalone Endpoints

GET /operational/config

Returns a minimal operational configuration payload to a trusted client IP. Used by the Auth H3 Client to coordinate cookie domains and token TTLs. Rejects all requests from untrusted IP addresses.

Access control

This endpoint uses IP-based access control rather than token authentication. Only the IP address configured in service.clientIp or service.proxy.ipToTrust is allowed.

Response (200)

{
  "domain": ".example.com",
  "accessTokenTTL": 900000
}

Responses on failure

GET /health

A basic health check endpoint registered directly on the Express app. Returns 200 OK as plain text. This route is exempt from HMAC verification when called from a local address.

Request Prerequisites

Every route that accepts a JSON body enforces the following rules:

• Content-Type: Must be application/json. The service returns 403 otherwise.
• Non-empty body: The body must not be empty. Empty payloads return 403.
• Body size limit: 1kb for most routes, 4kb for the OAuth route.
• Canary cookie: The canary_id cookie must be present on signup, login, and OAuth routes. Returns 400 if missing.

The canary_id cookie is set by the Bot Detector during the first visit. It ties the session to the originating device.

Route Summary