I IntelliAuth Docs

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

ts
useIntelliAuth(): IntelliAuthContext

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

tsx
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

tsx
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

tsx
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.

See also