Skip to main content
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 src/pages/api/theauth/[...path].ts. The [...path] spread catches every sub-path under /api/theauth/.
Or use the ALL handler to catch every HTTP method in one export:
Astro requires output: 'server' or output: 'hybrid' in astro.config.mjs to enable API routes. Static output mode does not support server-side route handlers.

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

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.

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.
Last modified on October 18, 2026