React SDK overview

The React SDK is the primary way browser-resident IntelliAuth applications integrate. It wraps the OAuth flows, the MFA prompts, the session storage, and the silent refresh, and exposes them as React-idiomatic primitives — a provider component and a single hook.

If you are building a SPA or a server-rendered React app, this is what you ship with. If you are building a Node backend, look at the Node SDK overview instead.

Install

pnpm add @intelliauth/react-sdk
# or: npm install @intelliauth/react-sdk
# or: yarn add @intelliauth/react-sdk

The package targets React 18+ and ships TypeScript types out of the box. No additional @types/ install is needed.

The two things you'll use most

Surface	Role
`<IntelliAuthProvider />`	Wraps your app. Holds the session, runs the silent-refresh loop, exposes context to consumers. You instantiate this once at the root.
`useIntelliAuth()`	The hook. Returns the user, the loading state, the error state, and 25+ methods (`loginWithRedirect`, `logout`, `getAccessToken`, etc.). Used everywhere downstream.

A typical app uses no other SDK surface for the basic flows.

The React SDK's pieces and how they relate. The two green boxes are what almost every app touches.

The other surfaces

Surface	When to reach for it
`AuthClient`	The underlying class the provider uses. Reach for it if you need IntelliAuth in a non-React context inside the same project — a service worker, a Web Worker, a legacy non-React component.
`IntelliAuthError` + `IntelliAuthErrorCode`	The error model. Catch + branch on error codes; show appropriate UI.
`attachFingerprint` + visitor helpers	Browser fingerprinting helpers used for risk-based authentication signals.

What the SDK does behind the scenes

You do not need to know this to use the SDK. It is useful to know when debugging:

Bootstrap. On mount, the provider checks for an existing session (silent auth via the IntelliAuth tenant's session cookie). If found, it fetches the user profile and primes the context.
Login redirect. loginWithRedirect() generates the PKCE code_verifier, stashes it in sessionStorage, generates a state parameter, and redirects the browser to /oauth2/authorize.
Callback handling. When the browser comes back to the registered callback URL, the SDK reads the code and state from the URL, validates state, exchanges the code at /oauth2/token, and stores the tokens.
Silent refresh. A background timer rotates the refresh token roughly 60 seconds before the access token's exp. If rotation fails (refresh token expired or revoked), the SDK clears the session and emits an error event.
Tab synchronisation. The SDK uses BroadcastChannel to share session state across browser tabs. A login in one tab is visible to all others within a few hundred milliseconds.

What the SDK does not do

Talk to your application's backend API. The SDK ships tokens; your code attaches them to fetch / axios / TanStack Query calls.
Render UI for the IntelliAuth login surface. The login page lives on the IntelliAuth tenant URL; the browser is redirected there.
Store user-facing application state. Your app's state (form values, UI preferences, etc.) lives in your own store.

Stability

The React SDK follows semver. Major versions ship breaking changes; minor versions add backwards-compatible features; patch versions are bugfixes. Reach for the latest tag in production unless your platform has a stricter pin policy.

What's next

Wire it up — start with the Quickstart — React. Once the basics work, the per-surface reference topics above are the reading order for deeper customisation.