Quickstart — React SPA - Authaz

// src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { AuthazProvider } from "@authaz/react";
import App from "./App";
 
ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <AuthazProvider basePath="/api/auth" autoRefresh>
      <App />
    </AuthazProvider>
  </React.StrictMode>
);

// src/components/Navbar.tsx
import { useAuthaz } from "@authaz/react";
 
export const Navbar = () => {
  const { isAuthenticated, isLoading, user, login, logout } = useAuthaz();
 
  if (isLoading) return <nav>…</nav>;
 
  return (
    <nav>
      {isAuthenticated ? (
        <>
          <span>{user?.email}</span>
          <button onClick={() => logout()}>Logout</button>
        </>
      ) : (
        <button onClick={() => login()}>Login</button>
      )}
    </nav>
  );
};

import { useUser } from "@authaz/react";
 
export const Profile = () => {
  const user = useUser();
  if (!user) return null;
 
  return (
    <div>
      <h2>{user.name ?? user.email}</h2>
      <p>MFA: {user.mfaEnabled ? "on" : "off"}</p>
      {user.organizations.map((org) => (
        <p key={org.organizationId}>
          {org.organizationId} — {org.accessLevel}
        </p>
      ))}
    </div>
  );
};

type AuthazUser = {
  id: string;
  email: string;
  name: string;
  mfaEnabled: boolean;
  organizations: { organizationId: string; accessLevel: string }[];
  tenantId?: string;
  organizationId?: string;
};

Hook	Use when
`useAuthaz()`	You need everything: user, state, `login`, `logout`, `refresh`.
`useUser()`	Just the user object. Returns `null` until loaded.
`useIsAuthenticated()`	Boolean — render-or-not decisions.
`useIsLoading()`	True while the initial `/me` call is in flight.
`useLogin()` / `useLogout()`	Stable callbacks — handy in event handlers and effects.
`useRequireAuth({ redirectTo? })`	Ensure the user is signed in for this page.
`useRequireUser({ redirectTo? })`	Same, but returns the user object once it resolves.

Symptom	Likely cause	Fix
Login button stays after sign-in; `useAuthaz()` returns `isAuthenticated: false`	Backend isn't reachable on the same origin — `/api/auth/me` is 404 or 401.	Check the backend is running. If frontend and backend are on different ports in dev, proxy `/api` (Vite snippet at the bottom of the Hono quickstart).
CORS error in console on `/api/auth/me`	Frontend and backend on different origins, no CORS config.	Either same-origin via dev proxy, or set CORS on the backend with `credentials: "include"` allowed.
`useAuthaz()` stuck on `isLoading: true`	`basePath` doesn't match where the backend mounted the handler.	The `basePath` prop on `AuthazProvider` must match the backend's mount path (default `/api/auth`).
`login()` redirects to a 404	Backend isn't serving `GET /api/auth/login`.	Confirm the Authaz handler is mounted at `basePath`.
Logged in, but reloading the page logs you out	Session cookie isn't being sent — likely a same-site or cross-origin issue.	In dev, prefer same-origin via proxy. In production, host frontend and backend under the same registrable domain.

Quickstart — React SPA

Prerequisites#

Step 1 — Install#

Step 2 — Wrap the app in `AuthazProvider`#

Step 4 — Protect a route#

Step 5 — Read the user#

Hook reference#

Calling Authaz from the frontend#

What success looks like#

If something's wrong#

Complete worked example#

Next steps#

Prerequisites#

Step 1 — Install#

Step 2 — Wrap the app in AuthazProvider#

Step 3 — Login / logout buttons#

Step 4 — Protect a route#

Step 5 — Read the user#

Hook reference#

Calling Authaz from the frontend#

What success looks like#

If something's wrong#

Complete worked example#

Next steps#

Step 2 — Wrap the app in `AuthazProvider`#