Use the TypeScript client
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:
| Frontend | Guide |
|---|---|
| React | React app |
| Vue | Vue app |
| Vanilla JavaScript or TypeScript | Vanilla browser |
| All of them | Browser, 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:
| Route | Served by | Notes |
|---|---|---|
GET /auth/login | AuthHandlers | The client navigates to it, with ?next= for the page to return to. |
GET /auth/me | AuthHandlers | { "user": …, "expiresAt": … } with the user in camelCase, or 401 SES_001. |
POST /auth/logout | AuthHandlers | Answers { "logoutUrl": … } when the request sends Accept: application/json. |
GET /auth/wallet, /auth/wallet/stats, /auth/models | AuthHandlers | Only 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/authand/apito the backend in development. - Base path. If you change
base_pathinAuthHandlers, pass the samebasePathto the TypeScript client. The registeredredirect_urimust end with<base_path>/callback. ai=for the wallet. The wallet and model hooks of the bindings need theaioption, 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.
Implement the stores
The contracts of SessionStore, GrantStore, GrantLock and ReplayStore, with SQLAlchemy and Redis sketches to adapt to your own database.
Call the LiteLLM gateway
Call LLMs and MCP tools through the gateway with the user's own token, handle empty wallets and rate limits, and attribute spend to a session.