Auth H3 Client

useAuthData

Vue composable that resolves the current authentication state from the auth status route, deduplicates SSR and hydration requests with a singleton, and exposes MFA challenges as a reactive ref.

useAuthData is the primary way to read authentication state in Vue components and pages. It calls the gateway's auth status route once, stores the result in a useState('auth') singleton, and returns a reactive Ref<AuthState> that every component in the tree can read without triggering a duplicate network request.

import { useAuthData } from 'auth-h3client/client'

const auth = await useAuthData()

During SSR the composable forwards all incoming request headers (cookies included) to the auth status route so the upstream check runs with the correct session. Any Set-Cookie headers returned by that route are captured and re-attached to the outgoing response, which means token rotation applied during the auth check is transparently visible to the browser.

During hydration, useAuthData uses the Nuxt getCachedData hook to return the SSR payload directly instead of issuing a second fetch. On subsequent calls after hydration, it refetches fresh state.

Signature

function useAuthData(authStatusUrl?: string): Promise<Ref<AuthState>>

Parameter	Type	Default	Description
`authStatusUrl`	`string`	`'/api/auth/users/authStatus'`	Endpoint path for the auth status check. This matches the Nuxt module default. In manual H3 or Nitro setups, pass the path you registered `getAuthStatusHandler` on.

Return type

interface AuthState {
  authorized: boolean
  mfaRequired: boolean
  id?: string
  message?: string
}

Field	Description
`authorized`	`true` when the session is valid and the user is logged in
`mfaRequired`	`true` when the IAM service returned a 202 MFA challenge
`id`	The user ID copied from `userId` on the IAM response when authorized
`message`	Human-readable instruction returned with the MFA challenge

Status code handling

HTTP status	`authorized`	`mfaRequired`	Notes
200	`true`	`false`	User is authenticated; `id` is set
202	`false`	`true`	MFA challenge; `message` carries the instruction text
401	`false`	`false`	Not authenticated
Any other error	`false`	`false`	Network or server error; fails silently

The MFA message defaults to "Multi factor authentication is required. Please check your email to continue." when the upstream response carries a text field but no explicit message, and to "Security check required." when neither is present.

Typical usage

pages/index.vue

<script setup lang="ts">
const auth = await useAuthData()

if (auth.value.mfaRequired) {
  // The IAM service has already sent the verification email.
  // Show a message telling the user to check their inbox.
} else if (!auth.value.authorized) {
  await navigateTo('/login')
}
</script>

Check mfaRequired before authorized to route the user correctly: during an MFA challenge, authorized is false but the user already has a pending session and should land on the verification page rather than the login page.

If you using this composable in a global Nuxt middleware avoid calling it on magic links routes, since users may be locked out completely, even when trying to prove their legitimacy or reset their passwords.

Custom endpoint

Pass a different path if you have registered the auth status handler under a non-default route:

const auth = await useAuthData('/api/my-auth-check')

Under the Nuxt module, the default is controlled by the authStatusUrl module option. Under plain H3 or Nitro, pass whichever path you registered getAuthStatusHandler on.

See Session Management for the server-side handler this composable talks to.

Client-side

useMagicLink