Skip to main content

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.
The client and the adapters in this repository do not fully line up yet. The adapters wrap every success body as { "data": ... } and the client returns the parsed body as is, without unwrapping it. The adapters answer a denied authorization with HTTP 403, which the client throws as a TheAuthApiError instead of returning allowed: false. And four client calls target paths the adapters do not serve: authorize (POST /agents/:id/authorize), authorizeByToken (POST /authorize with a bearer header; the adapters take agentId there and use POST /authorize/token for tokens), delegations.getEffectivePermissions (GET /delegations/:agentId/permissions), and all of mcp.* (/mcp/servers). The examples below show the API the client is typed for. Check it against your server before relying on it, or call the REST endpoints directly.

Installation

Creating a client

string
Base URL for the theAuth API, without a trailing slash.
string
default:"undefined"
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.
Record<string, string>
default:"{}"
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 throw TheAuthApiError 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.
client.agents.get and client.mcp.get return null for 404 rather than throwing. All other methods throw TheAuthApiError on any error response.

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:
Leave 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.
The store also has 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.
Last modified on October 19, 2026