Skip to content
IntelliAuth

Quickstart — React

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.

Before you begin
  • An IntelliAuth tenant URL (something like https://banking-cymmetri.intelliauth.local)
  • An application registered in that tenant (a SPA-type application)
  • The application's client id (copy from the application's detail page in the tenant admin console)
  • Node 18+ and a React 18+ project

1. Install the SDK

Section titled “1. Install the SDK”
Terminal window
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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “What&#39;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.