CIRCLE
Frontend

Use the TypeScript client

Pair the Python backend with the browser client and the React and Vue bindings of @circle-rd/auth-ai, which are documented in the TypeScript SDK site.

The Python package has no frontend code. The browser side of the backend-for-frontend model, the browser client and the React and Vue bindings, lives in the TypeScript package @circle-rd/auth-ai. It never holds a token: it only talks to the routes your backend mounts, using the session cookie. Because both SDKs share the same wire contract, those routes can be served by AuthHandlers from this package.

Use the TypeScript documentation for the frontend itself:

FrontendGuide
ReactReact app
VueVue app
Vanilla JavaScript or TypeScriptVanilla browser
All of themBrowser, React and Vue reference

What the frontend expects from your backend

The browser client calls these routes below a base path (/auth by default). AuthHandlers serves all of them with the answers the client reads:

RouteServed byNotes
GET /auth/loginAuthHandlersThe client navigates to it, with ?next= for the page to return to.
GET /auth/meAuthHandlers{ "user": …, "expiresAt": … } with the user in camelCase, or 401 SES_001.
POST /auth/logoutAuthHandlersAnswers { "logoutUrl": … } when the request sends Accept: application/json.
GET /auth/wallet, /auth/wallet/stats, /auth/modelsAuthHandlersOnly when you pass ai= to AuthHandlers. Wallet amounts are integer strings of micro-euros.

Errors use the same { "error": { "code", "message" } } envelope on both sides, with the same error codes, so the client turns them back into typed errors.

Three things to get right:

  • Same origin. The browser client sends its requests with the cookies of the current origin (credentials: "same-origin"). Serve the frontend from the same origin as the backend routes, or proxy /auth and /api to the backend in development.
  • Base path. If you change base_path in AuthHandlers, pass the same basePath to the TypeScript client. The registered redirect_uri must end with <base_path>/callback.
  • ai= for the wallet. The wallet and model hooks of the bindings need the ai option, as in the FastAPI backend guide.

A minimal check

With the FastAPI quick start running, the browser client reads the session like this:

import { createBrowserAuth } from "@circle-rd/auth-ai/client";

const auth = createBrowserAuth(); // basePath defaults to "/auth"

const user = await auth.getUser(); // null when signed out
if (user === null) {
  auth.login(); // navigates to /auth/login, then back to the current page
}

Entitlement checks in the browser (hasRole, hasPermission, hasFeature) only improve the interface: enforce them again in your Python routes, with has_role and the other helpers.

Copyright © 2026