CIRCLE
Frontend

React app

Add sign-in, entitlement checks and a live wallet balance to a React single-page app with AuthProvider and hooks.

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>
    </>
  );
}
  • status is "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 to next, 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.

Copyright © 2026