useIntelliAuth()

useIntelliAuth() is the primary consumer-side hook of the React SDK. Call it from any component wrapped in <IntelliAuthProvider> to read auth state and trigger flows. It exposes everything most apps need — current user, loading state, login + logout, token retrieval, session listing, MFA enrolment.

The hook is fully typed; importing the SDK gives you autocomplete for every method.

Signature

@intelliauth/react-sdkstable since v2.0.0useIntelliAuth

useIntelliAuth(): IntelliAuthContext

The primary React hook for IntelliAuth. Exposes auth state plus 25+ imperative methods covering login, logout, token retrieval, MFA, profile, sessions, and feature flags. Must be called from a component wrapped in `<IntelliAuthProvider>`.

No parameters. Call this hook from any descendant of <IntelliAuthProvider>.

Returns

IntelliAuthContext

Field	Type	Description
user	IntelliAuthUser \| null	Current authenticated user, or null when unauthenticated.
loading	boolean	True while the SDK is bootstrapping or refreshing a session.
error	IntelliAuthError \| null	Most recent SDK error; cleared on the next successful call.
loginWithRedirect	(options?: LoginOptions) => Promise<void>	Start the authorization-code-with-PKCE flow. Redirects to the IntelliAuth login surface.
logout	(options?: LogoutOptions) => Promise<void>	Clear the session and redirect to the logout return URL.
getAccessToken	(options?: TokenOptions) => Promise<string>	Return a valid access token, rotating the refresh token transparently when the cached token is stale.
forceRefresh	() => Promise<void>	Manually rotate the refresh token and refetch the user.
checkSession	() => Promise<boolean>	Silent session check (no UI). Returns true if a valid session exists.
listSessions	() => Promise<Session[]>	Fetch every active session for the current user across devices.
revokeSession	(sessionId: string) => Promise<void>	Revoke a specific session by id.

Errors

Code	Meaning	Recommended handling
session_expired	The refresh token can no longer mint access tokens.	Redirect to loginWithRedirect().
network_error	The SDK could not reach the auth endpoints.	Toast + retry button; do not redirect.
mfa_required	The session needs step-up before the requested scope.	Open the MFA challenge UI.
consent_required	The scope being requested has not been consented to.	Open the consent flow.
risk_challenge	The risk engine wants a CAPTCHA or challenge before proceeding.	Render the challenge widget.

The return value is one object with around 25 fields covering reactive state plus imperative actions. The reactive fields update across renders when the SDK pushes new state (auth events fire on every login, logout, token refresh, MFA challenge).

Common patterns

Gate a page on authentication

import { useIntelliAuth } from '@intelliauth/react-sdk'

export function ProtectedPage() {
  const { user, loading, loginWithRedirect } = useIntelliAuth()

  if (loading) return <Spinner />
  if (!user) {
    loginWithRedirect({ returnTo: window.location.pathname })
    return null
  }
  return <Dashboard />
}

Read the access token for an outbound request

const { getAccessToken } = useIntelliAuth()
const token = await getAccessToken({ audience: 'api.example.com' })
const res = await fetch('https://api.example.com/foo', {
  headers: { Authorization: `Bearer ${token}` },
})

getAccessToken() handles refresh-token rotation transparently — if the cached token has expired, the SDK rotates against the refresh token and returns the fresh one before resolving.

Listen for an MFA challenge

const { onMfaRequired, prepareMfaChallenge } = useIntelliAuth()

useEffect(() => {
  return onMfaRequired((flow) => {
    prepareMfaChallenge(flow.id, { factor: flow.preferredFactor })
  })
}, [onMfaRequired, prepareMfaChallenge])

Errors to handle

`IntelliAuthErrorCode`	When it fires	Recommended UI
`session_expired`	The refresh token can no longer mint access tokens	Redirect to `loginWithRedirect()`
`network_error`	The SDK could not reach the auth endpoints	Toast + retry button; do not redirect
`mfa_required`	The session needs step-up before the requested scope	Open the MFA challenge UI
`consent_required`	The scope being requested has not been consented to	Open the consent flow
`risk_challenge`	The risk engine wants a CAPTCHA or challenge before proceeding	Render the challenge widget

Branch on error.code rather than message strings — codes are stable across SDK versions.

What `useIntelliAuth()` does NOT do

It does not include sign-up flow (use useIntelliAuthSignUp()).
It does not expose admin management calls (use the Node SDK on the server).
It does not render UI — it returns state and callbacks. The UI is yours.