theAuthAstro(theauth, options?) returns named route handlers { GET, POST, PATCH, DELETE, OPTIONS, ALL }. Mount them in a catch-all API page so all theAuth paths are handled. Use individual named exports or the ALL catch-all handler.
Install
Setup
1
Create the theauth instance
2
Create the catch-all route
Create Or use the
src/pages/api/theauth/[...path].ts. The [...path] spread catches every sub-path under /api/theauth/.ALL handler to catch every HTTP method in one export:Options
theAuthAstro(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 locals.agent. Pass clientIp to feed ipAllowlist constraints.
MCP endpoints
Whenmcp 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 customauthenticate 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.
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
Related
Adapters overview
Compare all available framework adapters and their mount patterns.
SvelteKit
Edge-compatible adapter using +server.ts catch-all routes.
Next.js
App Router catch-all handler with MCP OAuth 2.1 support.
MCP
OAuth 2.1 authorization server endpoints mounted by the adapter.