<!-- llms.txt: https://workos.com/llms.txt -->

# Reauthentication

## Introduction

Re-authentication requires a user to actively sign in again to prove they authenticated recently, even when they already have a valid session. This is sometimes called step-up authentication, and it's useful before sensitive operations: changing security settings, irreversible deletes, or confirming a high-value action.

AuthKit implements this with two standard fields: the `auth_time` claim, which records when the user last authenticated, and the `max_age` parameter ([RFC-9470](https://datatracker.ietf.org/doc/html/rfc9470#section-3-5.4)), which indicates the allowed elapsed time since last authentication.

## (1) Read the `auth_time` claim

Every AuthKit access token includes an `auth_time` claim: a Unix timestamp, in seconds, of the user's most recent active authentication. It advances only from an active authentication, not from a refresh. Read it from the JWT and compare it against your freshness requirement.

```json
{
  "sub": "user_01EH...",
  "sid": "session_01HQ...",
  "auth_time": 1735680000,
  "iat": 1735683600,
  "exp": 1735684500
}
```

## (2) Prompt the user to re-authenticate

When the session isn't fresh enough, let the user know they need to sign in again to continue with the action.

## (3) Redirect to AuthKit with `max_age`

Send the user back through AuthKit, adding the `max_age` parameter to the [authorization URL](https://workos.com/docs/reference/authkit/authentication/get-authorization-url).

```ts
const authorizationUrl = workos.userManagement.getAuthorizationUrl({
  provider: 'authkit',
  clientId: process.env.WORKOS_CLIENT_ID!,
  redirectUri: process.env.WORKOS_REDIRECT_URI!,
  maxAge: 300,
});
```

Set `maxAge` to `0` to always force a fresh sign-in — useful when you've already confirmed the user's intent in your own UI.

AuthKit selects the re-authentication method for you based on the factors the user has, prompting for a password or MFA factor, or sending SSO users back through their identity provider.

When the user returns from AuthKit, their new access token carries an updated `auth_time`.

## Best practices

- **Avoid very short `max_age` values.** A `max_age` under 60 seconds forces users to re-authenticate almost immediately and is likely to frustrate them.
- **Return the user to where they left off.** Re-authentication redirects the user out of your app, so preserve the original location and any in-progress action with the [`state`](https://workos.com/docs/reference/authkit/authentication/get-authorization-url) parameter. AuthKit returns the exact value on the callback, letting you restore context so the user can continue with their high-value action.