Auth Flows

The module provides three ready-to-use controllers for the core credential flows. Each controller proxies to the IAM service over a signed connection and writes the resulting cookies to the response. The IAM service handles all credential validation, password hashing, anomaly detection, and rate limiting. See the IAM login, signup, and logout pages for the server-side details.

Registering routes

useAuthRoutes(router) registers all three controllers on an H3 router (v1) or H3 app (v2) in a single call. When using the Nuxt module, it is called automatically during plugin setup, so you do not need to call it yourself.

import { createRouter } from 'h3'
import { useAuthRoutes } from 'auth-h3client/v1'

const router = createRouter()
useAuthRoutes(router)

import { H3 } from 'h3'
import { useAuthRoutes } from 'auth-h3client/v2'

const app = new H3()
useAuthRoutes(app)

The registered routes are:

Each route enforces CSRF verification, Content-Type: application/json validation, and a 1 KB body limit before the controller runs. The logout route additionally rejects any request that carries a body or query string.

Login

loginHandler accepts { email, password } as a JSON body. It proxies the credentials to the IAM /login endpoint. On success, the IAM service returns an access token and issues a session refresh token cookie. The login handler writes two additional cookies to the response:

The session cookie from the IAM response is forwarded as-is via Set-Cookie headers.

After writing cookies the handler redirects to onSuccessRedirect with HTTP 303. When the request includes an Accept: application/json header, it returns JSON instead:

{ "ok": true, "redirectTo": "/dashboard" }

Error responses:

Signup

signUpHandler accepts the same pipeline as login: CSRF check, Content-Type validation, 1 KB body limit. It proxies the request body as-is to the IAM /auth/signup endpoint. The IAM service handles all validation: email uniqueness, password strength, disposable email detection, and credential hashing. On success, the handler sets the same cookies as login and redirects to onSuccessRedirect.

The body shape is determined entirely by the IAM service configuration. See IAM Signup for the required fields and schema.

Logout

logoutHandler sends a signed POST to the IAM /auth/logout endpoint with the session refresh token. On success, it deletes all session cookies from the response:

The handler also deletes the access token entry from the local LRU metadata cache so subsequent rotation checks do not find stale data.

The logout handler rejects requests that carry a body or a query string with HTTP 400 or 415. This prevents information leakage through unexpected payloads.

After clearing cookies the handler redirects to the root of the domain derived from operationalConfig.domain. When the request includes Accept: application/json, it returns:

{ "ok": true, "redirectTo": "/" }

Deduplication

All three controllers are wrapped with defineDeduplicatedEventHandler, which prevents concurrent execution of the same handler for a given request identity. If two login requests for the same session arrive simultaneously, only one is processed and the other waits for the result. This avoids race conditions during high-load scenarios such as double-submit from the frontend.