Reauthentication

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), which indicates the allowed elapsed time since last authentication.

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.

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

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

Send the user back through AuthKit, adding the max_age parameter to the authorization URL.

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.

• 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 parameter. AuthKit returns the exact value on the callback, letting you restore context so the user can continue with their high-value action.