---
url: "https://vueda.dev/v3/reference/api/js/use/useAuthFlow/functions/useAuthFlow.md"
title: "useAuthFlow"
---

# useAuthFlow

## Overview

Registers reauthentication routing behaviour, produces a submission error handler, and
provides a form context.

By default the form's action needs a recent session. Whenever `storeUser.authPendingFlow` is a
reauthentication flow, including when the form is set up, the user is sent to the reauthenticate route with the
current path as `redirect`. Every who-is response for a signed-in user whose session is no longer recent sets
that flow, including the refetch after a 401 response. The redirect therefore happens as soon as the store
learns that the session is stale, not only after a refused request.

The `storeUser` actions that need a recent session, such as `setupTOTPDevice` and `getRecoveryCodes`, refetch the
current user before they reject with an `UnauthorizedError`. The submission error handler reads that refetched
state. A signed-out user goes to the sign-in route. A pending reauthentication flow sends the user to the
reauthenticate route. An action that does not refetch leaves the state from before the request, so its
`UnauthorizedError` goes to the fallback handler.

The fallback handler is the `onSubmissionErrorHandler` option when given, and `defaultOnSubmissionError`
otherwise. It receives every error that the handler does not redirect for, and only those errors. A caller
therefore controls ordinary errors without reimplementing reauthentication.

The watch and the handler share one redirect for each pending flow, so the user sees one toast and one
navigation even when both react to the same refused request. When the router reports a failure for either
navigation, the handler passes the error to the fallback handler. The next refused submission tries the
redirect again.

With `requireRecentAuth: false`, a pending reauthentication flow does not redirect. A signed-out user still goes
to the sign-in route.

## Signature

`useAuthFlow(options)`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| <span id="param-options">options</span> | [AuthFlowOptions](/v3/reference/api/js/use/useAuthFlow/types/AuthFlowOptions.md) | yes |  |

### Returns

[AuthFlowContext](/v3/reference/api/js/use/useAuthFlow/types/AuthFlowContext.md)

## Examples

```js
// In a component that owns its own layout:
const formProps = reactive({ initialValues: { password: "" } });
const { formContext, onSubmissionErrorHandler, redirectTo } = useAuthFlow({ formProps });
```

## Source

`client/lib/use/useAuthFlow.js:80`