auth0-react: authentication state for a React single page app

What the SDK actually wraps

auth0-react is described simply as the Auth0 SDK for React Single Page Applications, and the package metadata says the same thing: description Auth0 SDK for React Single Page Applications (SPA), with keywords that include the Authorization Code Grant Flow, PKCE and Single Page Application authentication.

Those three keywords are the real content of the library. The Authorization Code Grant Flow with PKCE is the protocol a browser-based application has to use, because a client secret cannot be shipped to a browser, and the flow with a code verifier and challenge is how a public client proves it is the one that started the exchange. The SDK's job is to run that dance correctly, including the redirect back, and to keep the resulting session.

The API surface in the README is seven items, and they split into the modern and the classic.

The modern ones are Auth0Provider, which is the component that owns the session, Auth0ProviderOptions, which is its configuration type, and useAuth0, the hook your components call. There is also useAuth0Suspense, which is the same data delivered through a Suspense boundary rather than through a loading flag, and useEnterpriseConnect.

The classic ones are the higher order components, withAuth0, which injects the authentication state into a component, and withAuthenticationRequired, which is a route guard. Both are still supported, and the presence of both styles in the same list tells you the library is serving codebases that have not all migrated at the same time.

The package is published as @auth0/auth0-react, is MIT licensed, and the current version is 2.28.2, with 2.28.1 and 2.28.0 both published in early October 2026.

The provider, and the three URLs you have to get right

The setup has two halves, and the second one is where people get stuck.

First you create a Single Page Application in the Auth0 Dashboard. If you are using an existing application, the README tells you to verify the settings: open the Settings tab, scroll down to Show Advanced Settings, then on the OAuth tab ensure that JsonWebToken Signature Algorithm is set to RS256 and that OIDC Conformant is enabled.

Those two settings are not cosmetic. RS256 is the signing algorithm for the tokens, and the OIDC Conformant flag tells Auth0 to issue tokens that follow the OpenID Connect rules rather than its own legacy shape. A single page app SDK assumes OIDC conformant tokens, and the mismatch produces failures that look like decoding errors rather than configuration errors.

Then the Application URIs section, with three URLs:

- Allowed Callback URLs: `http://localhost:3000` - Allowed Logout URLs: `http://localhost:3000` - Allowed Web Origins: `http://localhost:3000`

The README notes that these should reflect the origins the application is running on, and that Allowed Callback URLs may also include a path depending on where you handle the callback. The three are different things and confusing them is a common source of a silent failure: the callback URL is where the browser lands after login, the logout URL is where the session ends, and the web origin is what the token is issued for.

From the Basic Information section you then take the Client ID and Domain, which are the two values the SDK needs. The domain is not a secret and the client ID is not a secret either, which is correct for a public client, but the SDK will also want to be told which URLs are legitimate so a malicious site cannot use your client ID to start a login and steal the result.

The provider wrapper and the useAuth0 hook

The SDK is configured by wrapping the application in Auth0Provider, and the React 18 form of the entry point looks like this:

// src/index.js
import React from 'react';
import { createRoot } from 'react-dom/client';
import { Auth0Provider } from '@auth0/auth0-react';
import App from './App';

const root = createRoot(document.getElementById('app'));

root.render(
  <Auth0Provider
    domain="YOUR_AUTH0_DOMAIN"
    clientId="YOUR_AUTH0_CLIENT_ID"
    authorizationParams={{
      redirect_uri: window.location.origin,
    }}
  >
    <App />
  </Auth0Provider>
);

The three props are the domain, the client ID, and the authorization params with a redirect_uri taken from window.location.origin. Using the current origin rather than a hard coded string is what lets the same build work on localhost and on a deployed host, provided the deployed origin is in the allowed list you configured earlier.

The README keeps the older React form in a collapsed section for React versions below 18, where the entry point uses ReactDOM.render with the element as a second argument rather than createRoot with a container. Both are provided because the SDK supports both React generations, and the difference is entirely in how the tree is mounted.

The component side then uses the useAuth0 hook, which returns the state and the methods:

// src/App.js
import React from 'react';
import { useAuth0 } from '@auth0/auth0-react';

function App() {
  const { isLoading, isAuthenticated, error, user, loginWithRedirect, logout } =
    useAuth0();

  if (isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div>Oops... {error.message}</div>;
  }

  if (isAuthenticated) {
    return (
      <div>
        Hello {user.name}{' '}
        <button onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}>
          Log out
        </button>
      </div>
    );
  } else {
    return <button onClick={() => loginWithRedirect()}>Log in</button>;
  }
}

export default App;

Three details in that example are worth copying exactly. The isLoading and error checks come first, before isAuthenticated, because the hook starts in a loading state while it restores a session, and rendering the signed out view during that window causes a visible flash and, worse, a redirect if you have a guard on the route. The logout call passes logoutParams with a returnTo, so the user comes back to your app rather than to a blank page. And loginWithRedirect is called with no arguments, so the provider configuration decides where the user ends up.

Anonymous sessions, and the experiments feature

Two features are marked as early access in the README, and both are worth understanding because they change what the SDK does before a user logs in.

Anonymous Sessions assigns a persistent identity to a visitor before they log in. That is the standard way to keep a cart, a reading list or an onboarding state across a session that has no account attached to it. You enable automatic creation on load with createAnonymousSessionOnFailedSilentAuth, and you control token storage with anonymousSessionsCacheMode, which is localStorage by default or memory for session-only storage. The access tokens and the session operations are then available through the anonymous property of the useAuth0 hook.

The default of localStorage is a decision with consequences. It means the anonymous identity survives a browser restart, which is usually what you want, and it also means the token sits in local storage, where any script on the page can read it. Choosing memory trades persistence for a smaller exposure window, and the README is neutral about which is right, which is appropriate because it depends on your threat model.

The Experiment Center feature is different in kind. Support via the SDKs is currently in Early Access and you have to request access by contacting your Auth0 representative. You can force a specific variant per login by passing experiment_id, variation_id and the optional segment_id in authorizationParams, and the README points at an Experiment Center example.

Both features are gated on a conversation with the vendor, which is worth knowing before you design around them. There is also a TROUBLESHOOTING.md and an FAQ.md in the repository, plus a MIGRATION_GUIDE.md, and the documentation list in the README covers a quickstart, a full sample application and an examples file with code samples for common React authentication scenarios.

The repository, the examples and the build

The repository layout shows a project with a lot of supporting infrastructure around a small library.

The tests are Jest with coverage, and there is a jest.config.js and jest.setup.js alongside a __tests__/ directory and a __mocks__/ directory. The end to end tests are Cypress, with a cypress.config.js and a cypress-bs.config.js, and the package scripts use start-server-and-test to bring up the API and the app before running them, for example the vite example on port 3000 with the API on 3001.

The examples are the interesting part for someone starting out, and there are four of them: a vite-react-router app, a gatsby-app, a nextjs-app and a users-api. The API example is the piece that makes the others work, because a single page application needs a backend to call with its access token, and the example set ships one. There are per-example start scripts, start:vite, start:gatsby, start:nextjs and start:api, and an install:examples script that installs each example with the legacy peer deps flag rather than pinning a lockfile per example.

The build is Rollup, and the build script runs the linter first and then rollup -c with NODE_ENV set to production. The published files are src and dist, with a CommonJS main at dist/auth0-react.cjs.js, an ES module at dist/auth0-react.esm.js and types at dist/index.d.ts, so the package supports both module systems and ships its own type declarations.

The documentation is generated with typedoc through two separate configurations, typedoc.js and typedoc.docsv2.js, which suggests the API reference is rendered in two forms, an older HTML site and a newer one. There is a .coderabbit.yaml and a .semgrepignore at the top level, an AGENTS.md and a CLAUDE.md, an opslevel.yml, and a CHANGELOG.md alongside the LICENSE.

Editorial conclusion

Adopt auth0-react when you are building a React single page application and want Auth0 to handle login, logout and token storage rather than implementing the authorization code flow with PKCE yourself, because the SDK gives you the provider, the hook and the route guards in one consistent shape. Do not adopt it for a server rendered application, since the package is explicitly scoped to SPAs and its token handling assumes the browser holds the session. Before you start, create a Single Page Application in the Auth0 Dashboard, set the allowed callback, logout and web origin URLs to the origins you actually run on, and confirm that the JsonWebToken Signature Algorithm is RS256 and that OIDC Conformant is enabled.

Frequently asked questions

Official sources

1. auth0/auth0-react on GitHub
2. Issues
3. License: MIT
4. README
5. Releases