Routes Reference

The module ships four route registrars that mount authentication, OAuth, magic link, and bounce routes on an H3 router or app. It also exports two standalone handlers: getAuthStatusHandler for session status checks and getApiListsController for API token inventory routes. Register them explicitly during startup by calling each registrar with your router or app instance, as shown in the H3 and Nitro setup guide. When using the Nuxt module, the registrars are still configured in your Nitro plugin, while the module auto-registers the auth status route regardless of enableMiddleware, and can optionally auto-register the API token list route when registerApiRoute is configured.

import { H3 } from 'h3'
import {
  configuration,
  useAuthRoutes,
  useOAuthRoutes,
  bounceRouter,
  magicLinksRouter,
} from 'auth-h3client/v2'

configuration({ /* ... */ })

const app = new H3()
useAuthRoutes(app)
useOAuthRoutes(app)
bounceRouter(app)
magicLinksRouter(app, 'api')

For the global middleware chain applied before any route handler runs, see Security: Request Lifecycle.

useAuthRoutes

Core signup, login, and logout routes. Every route in this registrar verifies the CSRF cookie before the handler runs.

POST /signup

Proxies the request body to the IAM /auth/signup endpoint. On success, sets the __Secure-a and a-iat cookies and redirects to onSuccessRedirect. Returns JSON for requests with Accept: application/json.

Middleware chain

Request body

Cookies set on success

Responses

See Auth Flows for the full signup flow.

POST /login

Authenticates a user with email and password. On success, sets the same cookies as signup and redirects or returns JSON.

Middleware chain

Request body

Cookies set on success

Responses

See Auth Flows for the login pipeline and cookie details.

POST /logout

Sends the refresh token to the IAM /auth/logout endpoint, then clears the session cookies and removes the access token from the local LRU cache. Rejects any request body.

Middleware chain

Cookies required

Cookies cleared on success

__Secure-a, a-iat, session, iat

Responses

See Auth Flows for the full logout sequence.

useOAuthRoutes

OAuth and OIDC authorization code flows. Both GET and POST are registered on the callback route to support providers that use response_mode: form_post.

GET /oauth/:provider

Looks up the provider by the :provider parameter, generates a PKCE verifier and challenge pair, creates a signed state cookie, and redirects the user to the provider's authorization URL. For OIDC providers, discovers the authorization endpoint via {issuer}/.well-known/openid-configuration.

Middleware chain

No pipeline middleware. The handler (OAuthRedirect) handles provider lookup and validation internally.

URL parameters

Cookies set

Responses

See OAuth for provider configuration and the PKCE flow.

GET /oauth/callback/:provider and POST /oauth/callback/:provider

Handles the provider callback. Verifies the state cookie, exchanges the authorization code for tokens, verifies the ID token signature against the provider's JWKS endpoint (OIDC), validates the at_hash claim (OIDC), fetches user info, merges the profile with safeObjectMerge to protect reserved JWT fields, and proxies the result to the IAM service. On success, sets the access and session cookies.

Middleware chain

URL parameters

Cookies set on success

Responses

See OAuth for the full OIDC verification flow and safeObjectMerge behavior.

magicLinksRouter

Handles MFA verification, password reset, and email change flows. Registered with the api prefix, so all paths are /api/auth/.... GET routes set Cache-Control: no-store and generate a fresh CSRF cookie for the page that will be rendered. POST routes require CSRF verification.

GET /api/auth/verify-mfa

Validates an MFA magic link and returns link metadata. Used by the useMagicLink composable when the reason is MAGIC_LINK_MFA_CHECKS.

Middleware chain

Query parameters

Responses

POST /api/auth/verify-mfa

Submits an MFA code after the magic link is verified. Verifies the link first, then validates and forwards the code to the IAM service.

Middleware chain

Request body

Responses

See Built-in MFA for the full flow.

POST /api/auth/password-reset

Initiates a password reset by sending a signed magic link email to the provided address.

Middleware chain

Request body

Responses

See Password Reset for the full flow.

GET /api/auth/reset-password

Validates a password reset magic link and returns link metadata. Used by the useMagicLink composable when the reason is PASSWORD_RESET.

Middleware chain

Query parameters

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

Responses

POST /api/auth/reset-password

Submits a new password to complete the reset flow after the magic link is verified.

Middleware chain

Request body

Responses

See Password Reset for the complete three-step flow.

POST /api/auth/change-email

Initiates the email change flow for an authenticated user. Validates the session, generates a 128-byte random token, and calls askForMfaFlow to send a verification email to the user's current address.

Middleware chain

Request body

Responses

See Email Change for the three-step flow.

GET /api/auth/update-email

Validates an email change magic link and returns link metadata. Used by the useMagicLink composable when the reason is change_email.

Middleware chain

Query parameters

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

Responses

POST /api/auth/update-email

Submits the new email address with the magic link query parameters and verification code to complete the email change. Applies token rotation on success.

Middleware chain

Query parameters

Request body

Cookies set on success

Responses

See Email Change for the complete flow.

bounceRouter

GET /auth/bounce

Reads the magic link query parameters from the incoming email URL and redirects to magicLinkRedirectPath with the parameters re-encoded in the query string. This converts an externally-deliverable bounce URL into an internal client-side route.

The bounce path is configurable via magicLinkBouncePath (default /auth/bounce). The destination is controlled by magicLinkRedirectPath.

Query parameters

Responses

See Built-in MFA and Password Reset for the full magic link flows that use this bounce route.

Auth status endpoint

GET /auth/users/authStatus

Returns the current session state by proxying to the IAM /secret/data endpoint. In manual H3 and Nitro setups, /auth/users/authStatus is the most common path. When using the Nuxt module, the handler is registered automatically at authStatusUrl, whose default value is /api/auth/users/authStatus.

If you want to register the same handler with addServerHandler() instead of importing it from auth-h3client/v1 or auth-h3client/v2, use the auth-h3client/server/auth-status export.

Cookies required

Responses

See Session Management for how useAuthData reads this endpoint.

API token inventory endpoint

GET <registerApiRoute.path>

Returns the authenticated user's API token inventory by proxying to the IAM /api/manage/list-metadata endpoint. This handler is exported as getApiListsController. Register it manually on any GET route, or let the Nuxt module register it automatically by setting registerApiRoute.path.

For Nuxt module wiring and manual addServerHandler() setups, use the auth-h3client/server/api-lists export.

The handler runs the same authenticated session pipeline as getAuthStatusHandler, then removes public_identifier from every token entry before returning the response. The response includes token IDs, names, privilege levels, expiry timestamps, usage counts, and optional IP restrictions.

Cookies required

Responses

Each tokenList entry includes the token id, name, created_at, expires_at, restricted_to_ip_address, last_used, usage_count, and privilege_type. The response omits public_identifier.

Route summary