Skip to main content

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 with TheAuthProvider. In Next.js App Router, create a client component and import it from your root layout.
string
default:"\"/api/theauth\""
Path to your theAuth API handler. Must match the route you mounted in the adapter.
ExternalAuthConfig
default:"undefined"
Delegate authentication to an external API instead of the managed mode described below. See “External auth mode”.
ManagedAuthConfig
default:"undefined"
Options for managed mode: emailPassword, refetch (focus, reconnect, interval), initialSession (SSR seed), signInPath, signUpPath and identifierField. See Session refetch and SSR.
boolean
default:"false"
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

Pass managed={{ 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".
Without emailPassword, managed mode signs in and up through the username module: POST {basePath}/auth/username/sign-in and POST {basePath}/auth/username/sign-up with { username, password }, answering { user, session: { token, expiresAt } }. createTheAuthHandler does not serve those two routes. Forward them yourself with theauth.username.handleRequest(request). To use routes of your own set managed.signInPath, managed.signUpPath and managed.identifierField, and return the same response shape.

useSession

Returns the raw session object. Useful when you need the session token or expiry directly.
TheAuthSession | null
The current session ({ token, user, expiresAt? }). Null when unauthenticated or still loading.
boolean
True during the initial session restore.
() => Promise<void>
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.
TheAuthUser | null
The authenticated user ({ id, email?, name?, image? }). Null when unauthenticated.
boolean
True when a valid session with a user is present.
boolean
True during the initial load. Avoid rendering auth-gated UI until this is false.

useSignIn

Handles email and password sign-in. Returns signIn(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 with signUp(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.
The hook calls 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 }.
TheAuthAgent[]
Current list of agents for the authenticated user.
(input: CreateAgentInput) => Promise<ActionResult<TheAuthAgent>>
Create a new agent. CreateAgentInput requires ownerId, name, type, and permissions. The list reloads on success.
(agentId: string) => Promise<ActionResult>
Revoke an agent by ID. The list reloads on success.
(agentId: string) => Promise<ActionResult<TheAuthAgent>>
Rotate an agent’s token. The returned agent carries the new token.
() => Promise<void>
Re-fetch the agent list manually.
boolean
True while the agent list is loading.
string | null
The last load error message.
ActionResult<T> is { success: true, data: T } | { success: false, error: string }.

External auth mode

Pass external 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.
Last modified on October 19, 2026