Skip to main content
theAuthTanStack(theauth, options?) returns named route handlers { GET, POST, PATCH, DELETE, OPTIONS }. Mount them in a splat API route file so all theAuth paths are handled.

Install

Setup

1

Create the theauth instance

2

Create the catch-all route

Create app/routes/api/theauth.$.ts. The $ splat segment catches every sub-path under /api/theauth/.
TanStack Start API routes receive a standard Web API Request, so the adapter delegates directly to the theAuth dispatcher without any conversion.

Options

theAuthTanStack(theauth, options?) takes the same options as the core handler (createTheAuthHandler from @glinr/theauth/http), so they are identical on every adapter: Every route and status code is listed on the route reference.

Protect a route with requireScope

requireScope(theauth, { action, resource }, handler) reads the agent bearer token and checks it may perform the action. It answers 401 (invalid_token, agent_not_found, agent_revoked, agent_expired) or 403 (any other denial) with body { "error": { "code", "message" } }, and otherwise passes the agent (without its token) on via the second argument (and context.agent when the route context has one). Pass clientIp to feed ipAllowlist constraints.

MCP endpoints

When mcp is passed, the MCP OAuth 2.1 endpoints are available at:

Management routes and client IP

With the default session guard, a signed-in user only acts on their own agents, delegations and audit rows. A custom authenticate resolver is a trust decision and sees everything. The adapter does not read forwarded headers for the client IP. Behind a proxy, set trustedProxy with trustedProxyCount or trustedHeader, or ipAllowlist constraints cannot match.
On Cloudflare use trustedHeader: 'cf-connecting-ip'. Only trust a header your edge overwrites.

Endpoint reference

See the route reference for every route, its auth level and status codes.

Full example

Adapters overview

Compare all available framework adapters and their mount patterns.

SolidStart

Similar Web-standard Request adapter using a splat-route pattern.

Next.js

App Router catch-all handler with MCP OAuth 2.1 support.

MCP

OAuth 2.1 authorization server endpoints mounted by the adapter.
Last modified on October 18, 2026