React app
The React bindings read the session through your backend's /auth routes. They hold no token. You need the Fastify backend (or another bridge) running, with the ai option if you want the wallet and model hooks. Requires react >=18.
Provider
Wrap the app once. The provider reads the session on mount and again when the tab becomes visible.
import { createRoot } from "react-dom/client";
import { AuthProvider } from "@circle-rd/auth-ai/react";
import { App } from "./App";
createRoot(document.getElementById("root")!).render(
<AuthProvider>
<App />
</AuthProvider>,
);
AuthProvider takes optional props: basePath (default "/auth"), refreshOnFocus (default true) and auth (a prebuilt BrowserAuth, handy in tests).
Sign-in and entitlements
import { useAuth, useEntitlements } from "@circle-rd/auth-ai/react";
export function App() {
const { status, user, error, login, logout } = useAuth();
const { hasRole, hasFeature, getFeature } = useEntitlements();
if (status === "loading") return <p>Loading…</p>;
if (!user) {
return (
<>
<button onClick={() => login()}>Sign in</button>
{error && <p>Could not read the session ({error.code}).</p>}
</>
);
}
return (
<>
<p>Signed in as {user.name ?? user.email ?? user.sub}</p>
{hasRole("admin") && <a href="/admin">Administration</a>}
{hasFeature("beta") && <p>Beta enabled, seats: {String(getFeature("seats") ?? 0)}</p>}
<button onClick={() => void logout()}>Sign out</button>
</>
);
}
statusis"loading","authenticated","unauthenticated"or"error". A failed refresh keeps the last known user, so a network blip does not sign anyone out.login(next?)sends the browser to the sign-in and back tonext, the current path by default.logout()ends the session and navigates to the provider's logout URL.useEntitlements()returns checks that are all false when signed out. They improve the interface only: enforce every entitlement on the server.
Wallet and models
import { useModels, useWallet } from "@circle-rd/auth-ai/react";
import { formatEuros } from "@circle-rd/auth-ai/client";
export function Credit() {
const wallet = useWallet({ pollIntervalMs: 15_000 });
const models = useModels();
if (wallet.status === "error") return <p>Wallet unavailable ({wallet.error?.code}).</p>;
if (!wallet.data) return <p>Loading…</p>;
return (
<>
<p>
Balance: {formatEuros(wallet.data.balance)} €{" "}
{!wallet.data.canSpend && <a href={wallet.data.topupUrl}>Top up</a>}
</p>
<ul>{models.data?.map((model) => <li key={model.id}>{model.id}</li>)}</ul>
</>
);
}
wallet.data.balance is a bigint of micro-euros: always format it with formatEuros. Decide whether a paid action may start from canSpend, not from the balance. useWalletStats(days?) is the same for spend statistics. All three return { status, data, error, refresh }. A 401 from one of them refreshes the auth state, so your UI falls back to the sign-in.
Development with a dev server
The cookie is set by your backend, so the frontend must reach /auth and /api on the same origin as the page. With Vite, proxy them and register the dev origin in auth-service:
// vite.config.ts
import { defineConfig } from "vite";
export default defineConfig({
server: {
proxy: {
"/auth": "http://localhost:3000",
"/api": "http://localhost:3000",
},
},
});
Configure the backend with redirectUri: "http://localhost:5173/auth/callback" (HTTP is accepted for localhost) and register the same URI in auth-service, so the origin the SDK builds URLs on is the one your browser uses.