Overview
@glinr/theauth-client is a typed HTTP client for the theAuth REST API. It covers agents, authorization, delegations, audit logs, and MCP server registration.
Zero dependencies. No Node.js builtins. Works in browser, Node.js, Deno, and Bun, anywhere the Fetch API is available.
Installation
Creating a client
Bearer token sent as
Authorization: Bearer <token> on every request. The adapters protect /agents, /delegations, /audit and POST /authorize, so this must be a credential your adapter’s authenticate function accepts (a theAuth session token when you rely on auth.session). An agent token is not accepted there. See Adapters.Extra headers merged into every request. Useful for API gateways that require custom headers.
Agents
Authorization
Two paths: by agent ID (when you manage the agent directly) or by raw bearer token (when the token comes in from an HTTP request).Delegations
Audit log
Error handling
All methods throwTheAuthApiError when the server returns a non-2xx response or the network call fails.
TheAuthApiError also covers network errors: if fetch itself throws, you get code: 'NETWORK_ERROR' and status: 0.
MCP servers
These calls hit/mcp/servers, which the bundled adapters do not serve (see the warning above). In your own server code, use the in-process registry theauth.mcp.register, list, and get instead.
Session refetch and SSR
createSessionStore keeps a session in step with the server. It is the same store the React, Vue, Svelte and Solid bindings use.
The triggers run while the store has at least one subscriber and stop when the last one leaves.
store.startAutoRefresh(options) starts them by hand and returns a stop function, store.destroy() stops them and aborts a refresh in flight. With no window (a server, a worker, an edge runtime) every trigger is a no-op, so the same code runs there. refetch.env takes your own window, document and isOnline, which is how the tests drive it with fake event targets.
store.refresh() calls GET {basePath}/auth/session. Concurrent calls, such as focus and visibility firing together, share one request. A 401 or 403 clears the session. A network error or a 5xx keeps what the store has, so a dropped connection does not sign anyone out. A sign out that happens while a refresh is running wins over the refresh result.
For SSR, resolve the session on the server and seed the store so the first render matches and no request is needed:
token out of the HTML you render. Cookie sessions do not need it, and the store asks the server again on the next refresh. An expired or malformed value counts as signed out, and hydrateSession(null) means the server found no session. Neither the store nor the refetch code logs anything, and no error message contains a token.
The routes the store calls are POST /auth/sign-out, GET /auth/session, and either the username routes (/auth/username/sign-in and /auth/username/sign-up, which you forward with theauth.username.handleRequest) or, with emailPassword: true, the core email and password routes that createTheAuthHandler serves (/auth/email/sign-in and /auth/email/sign-up, body field email). Set signInPath, signUpPath and identifierField if you serve your own.
resendVerification(email), requestPasswordReset(email) and resetPassword(token, password). See Email and password for the server side and the error codes.
Next steps
Agent identity
Understand the agent model before building integrations.
Audit log
Querying and exporting the audit trail.
Delegation chains
How delegated permissions work.