Overview
@glinr/theauth-react provides React hooks and a context provider for building auth UIs on top of theAuth. It works with Next.js App Router, Next.js Pages Router, Vite, and any React 18+ setup (the package declares React 18 or later as a peer dependency).
The package itself has no Node.js dependencies, it runs entirely in the browser. Your theAuth API handler can sit behind Next.js Edge Runtime, Cloudflare Workers, Deno Deploy, or any other edge runtime, and the hooks talk to it over standard fetch.
All hooks must be rendered inside
TheAuthProvider. The provider talks to your theAuth API route, no direct database access from the browser.Installation
Provider setup
Wrap your app withTheAuthProvider. In Next.js App Router, create a client component and import it from your root layout.
Path to your theAuth API handler. Must match the route you mounted in the adapter.
Delegate authentication to an external API instead of the managed mode described below. See “External auth mode”.
Options for managed mode:
emailPassword, refetch (focus, reconnect, interval), initialSession (SSR seed), signInPath, signUpPath and identifierField. See Session refetch and SSR.Enable verbose auth state logging (also enabled when
localStorage.DEBUG === "theauth").In managed mode (no
external prop) the session token is stored in localStorage under the key theauth_session. On load the provider shows that stored session at once, then confirms it with GET {basePath}/auth/session. A 401 or 403 clears it. A network error or a 5xx keeps it, so going offline never signs anyone out. Cookie-only sessions work too: with nothing stored, the same request picks up the session cookie.Email and password
Passmanaged={{ emailPassword: true }} to use the core emailPassword routes: POST {basePath}/auth/email/sign-in and POST {basePath}/auth/email/sign-up with { email, password } (plus name for sign-up). The server side is the emailPassword config key, see Email and password. With email verification on (the default), signUp succeeds with data.verificationRequired === true and signs nobody in. A sign-in before verification fails with code: "EMAIL_NOT_VERIFIED".
useSession
Returns the raw session object. Useful when you need the session token or expiry directly.The current session (
{ token, user, expiresAt? }). Null when unauthenticated or still loading.Re-read the session from the server. In managed mode this calls
GET {basePath}/auth/session, in external mode it re-fetches the current user. Concurrent calls share one request.useUser
Returns the authenticated user and a boolean flag. This is the most common hook for protecting UI.The authenticated user (
{ id, email?, name?, image? }). Null when unauthenticated.useSignIn
Handles email and password sign-in. ReturnssignIn(email, password) plus isLoading and error (a string or null).
The hook posts to POST {basePath}/auth/username/sign-in by default, or POST {basePath}/auth/email/sign-in with managed.emailPassword (see the notes above about the server route). A failed result carries the server’s code when it sent one.
useSignUp
Handles new account registration withsignUp(email, password, name?). Posts to POST {basePath}/auth/username/sign-up by default, or POST {basePath}/auth/email/sign-up with managed.emailPassword. The result is { success: true, data: { verificationRequired } }: when verificationRequired is true the account exists but there is no session yet, so show a “check your inbox” screen.
useEmailPassword
For the email and password routes (managed={{ emailPassword: true }}). Returns verifyEmail(token), resendVerification(email), requestPasswordReset(email) and resetPassword(token, password). Each resolves to an ActionResult with the server code on failure. requestPasswordReset and resetPassword need passwordReset on the server. In external mode they return a failure result.
useSignOut
Signs the user out.signOut() takes no arguments. In managed mode it clears React state and localStorage first, then calls POST {basePath}/auth/sign-out to revoke the session on the server (the stored token goes as a bearer header, the cookie is sent too). In external mode it calls your logout path. It does not redirect, navigate yourself afterwards.
useAgents
Lets your UI list, create, revoke, and rotate agents through your theAuth API.useAgents(basePath = '/api/theauth') takes its own base path and reads the user from the provider.
GET {basePath}/agents?userId=<id> (expecting { data: Agent[] }), POST {basePath}/agents, DELETE {basePath}/agents/:id, and POST {basePath}/agents/:id/rotate, all with credentials: 'include'. Single-agent responses are expected as { data: Agent }.
Create a new agent.
CreateAgentInput requires ownerId, name, type, and permissions. The list reloads on success.Rotate an agent’s token. The returned agent carries the new token.
ActionResult<T> is { success: true, data: T } | { success: false, error: string }.
External auth mode
Passexternal to delegate authentication to an API you already run, for example one that manages httpOnly cookies. The provider then fetches the user from apiUrl + mePath (default /api/auth/me), sends login redirects to loginPath (default /auth/github), and calls logoutPath (default /auth/logout, method POST) on sign out. No session is stored in localStorage. external.refetch and external.initialUser work the same way as in managed mode, and a network error during a refetch keeps the current user.
useRotateSession() returns { rotate, status, isOnline } for the token rotation flow. It only does work when refreshPath is set, otherwise rotate() resolves with { success: false, code: 'network_error' }.
Next steps
TypeScript client
Server-side and Node.js usage with @glinr/theauth-client.
Agent identity
How agents are modelled and what fields they carry.
Adapters
Mount the theAuth handler in Next.js, Express, Hono, and others.