Five minutes from npm install to a working sign-in button. This walks the minimum viable React integration. Anything you want to customise after this — branding, MFA prompts, custom error handling — has its own topic; come back when the basics work.

1. Install the SDK

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

The package ships TypeScript types out of the box. No additional @types/ package needed.

2. Wrap your app in IntelliAuthProvider

The provider holds the SDK's state (current user, in-flight refresh, etc.) in a React context. Every component that uses the useIntelliAuth() hook reads from this context.

// src/main.tsx (or wherever your app's entry point is)
import { IntelliAuthProvider } from '@intelliauth/react-sdk'
import { createRoot } from 'react-dom/client'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <IntelliAuthProvider
    tenantUrl="https://banking-cymmetri.intelliauth.local"
    clientId="app_01HZX..."
    redirectUri={`${window.location.origin}/callback`}
  >
    <App />
  </IntelliAuthProvider>,
)

Three props:

• tenantUrl — your tenant's base URL.

• clientId — the SPA application's client id from the tenant admin console.

• redirectUri — where IntelliAuth sends users back after sign-in. Must match a redirect URI registered on the application; commonly ${window.location.origin}/callback.

3. Use the hook

useIntelliAuth() is the only thing you need from the SDK in 90% of cases.

// src/App.tsx
import { useIntelliAuth } from '@intelliauth/react-sdk'

export default function App() {
  const { user, loading, loginWithRedirect, logout } = useIntelliAuth()

  if (loading) return <p>Loading…</p>

  if (!user) {
    return (
      <button onClick={() => loginWithRedirect()}>
        Sign in with IntelliAuth
      </button>
    )
  }

  return (
    <div>
      <p>Hello, {user.email}</p>
      <button onClick={() => logout()}>Sign out</button>
    </div>
  )
}

That's the full integration. Click "Sign in", you're redirected to the IntelliAuth login surface, sign in, get redirected back to /callback, the SDK exchanges the authorization code for tokens, and useIntelliAuth() returns the user.

4. Handle the callback route

The SDK exchanges the authorization code automatically when it boots, but you do need a route at the redirect URI that mounts the provider. The simplest pattern with React Router:

import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'

function CallbackPage() {
  const { loading } = useIntelliAuth()
  return loading ? <p>Signing in…</p> : <Navigate to="/" replace />
}

<BrowserRouter>
  <Routes>
    <Route path="/" element={<App />} />
    <Route path="/callback" element={<CallbackPage />} />
  </Routes>
</BrowserRouter>

When the user lands at /callback, the SDK reads the code from the URL, exchanges it for tokens, and updates the context. Once loading flips to false, the redirect to / lands the user back in the app, signed in.

5. Call your API with the access token

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

getAccessToken() handles refresh-token rotation transparently. If the cached token is stale, the SDK refreshes it before resolving.

What's next

• Customise the login surface — branding lives on the tenant, see Tenant admin / Branding.

• Add MFA — enable it on the tenant; the SDK surfaces an mfa_required error code your UI handles.

• Open the useIntelliAuth() reference for the other 20+ methods on the hook.

See also

• Install the React SDK

• Sample apps

• useIntelliAuth() reference