Auth0 SPA JS SDK

The SDK manages MFA by intercepting authentication failures and providing a specialized mfa API. When an authentication attempt requires MFA, the SDK throws an MfaRequiredError containing an mfa_token.

There are two primary flows based on the mfa_requirements object in the error response:

1. Challenge Flow (mfa_requirements.challenge): The user has already enrolled authenticators. You should use getAuthenticators() $\rightarrow$ challenge() $\rightarrow$ verify().
2. Enroll Flow (mfa_requirements.enroll): The user needs to set up MFA. You should use getEnrollmentFactors() $\rightarrow$ enroll() $\rightarrow$ verify().

The SDK automatically handles the context, so you can call MFA methods using the mfa_token from the error.

NOTE

MFA support is currently in Early Access. Contact your Auth0 representative to request access.

// Example of detecting MFA requirement
try {
  await auth0.getTokenSilently();
} catch (error) {
  if (error instanceof MfaRequiredError) {
    const mfaToken = error.mfa_token;
    // Proceed to either enrollment or challenge flow
  }
}

Native to Web SSO allows users transitioning from a native mobile app to a web app to maintain their session. The SDK can automatically detect a session transfer token in the URL query parameters.

Automatic Detection

1. Configure sessionTransferTokenQueryParamName in createAuth0Client with the name of the query parameter used by your native app (e.g., 'session_transfer_token').
2. When the web app is loaded with that parameter in the URL, the SDK automatically extracts it and includes it in the subsequent /authorize request via loginWithRedirect() or loginWithPopup().
3. Cleanup: The SDK automatically removes the token from the URL using window.history.replaceState() after extraction to prevent reuse.

Manual Provisioning

You can override automatic detection by manually providing the session_transfer_token in authorizationParams. Note that when providing it manually, the SDK will not automatically clean the URL.

// 1. Configure detection
const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  sessionTransferTokenQueryParamName: 'session_transfer_token',
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

// 2. Use automatically (token is extracted from URL and cleaned)
await auth0.loginWithRedirect();

// OR: Manual override (URL is NOT cleaned)
const params = new URLSearchParams(window.location.search);
const sessionTransferToken = params.get('my_custom_param');

if (sessionTransferToken) {
  await auth0.loginWithRedirect({
    authorizationParams: {
      session_transfer_token: sessionTransferToken
    }
  });
}

If your upstream Identity Provider (like Okta) supports session expiry, Auth0 can include a session_expiry claim in the ID token. This claim is a Unix timestamp in seconds.

Behavior: When the current time reaches the session_expiry timestamp (with a 30-second clock-skew tolerance), the SDK automatically tears down the local session.

Important:

• getUser(), getTokenSilently(), getIdTokenClaims(), and isAuthenticated() will all return undefined or false once the ceiling is reached.
• Silent token refreshes cannot extend this session.
• You must add null checks to your application code to handle the case where a user's session has expired upstream.

// Graceful handling of expired upstream sessions
const token = await auth0.getTokenSilently();

if (!token) {
  // Session expired upstream, redirect to login
  await auth0.loginWithRedirect();
  return;
}

fetch('/api/data', {
  headers: { Authorization: `Bearer ${token}` }
});

Online Refresh Tokens (ORTs) are a refresh token type bound to the lifetime of the user's Auth0 session. They are useful for SPAs that want a renewal path that tracks the SSO session rather than living independently.

Key Characteristics:

• Session-bound: Valid only while the underlying Auth0 session is active. If the session ends (via logout, idle expiry, or admin revocation), the ORT stops working.
• Non-rotating: Refreshing an access token with an ORT does not issue a new refresh token. The same ORT is reused for the life of the session.
• Requires DPoP: Because ORTs are non-rotating, sender-constraining the token via DPoP is mandatory to mitigate replay attacks. You must explicitly set useDpop: true.

WARNING

Online Refresh Tokens do not currently support resource servers with Ephemeral Sessions enabled. If a resource server has both allow_online_access and "Allow for Ephemeral Sessions" enabled, the ORT will be rejected with invalid_grant ("Unknown or invalid refresh token") on the next refresh. Disable "Allow for Ephemeral Sessions" on your resource server when using refreshTokenMode: RefreshTokenMode.Online.