Astro

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

pnpm add @glinr/theauth @glinr/theauth-astro

Setup

Create the theauth instance

// src/lib/theauth.ts
import { createTheAuth } from '@glinr/theauth';
import { createMcpModule } from '@glinr/theauth/mcp';
import { mcpStore } from './mcp-store'; // storage callbacks, see the MCP page

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: import.meta.env.DATABASE_URL },
  baseUrl: import.meta.env.AUTH_BASE_URL,
  mcp: { enabled: true }, // creates the MCP tables
});

// baseUrl is the public origin plus the adapter mount path (default /api/theauth)
export const mcp = createMcpModule({
  config: {
    enabled: true,
    issuer: import.meta.env.AUTH_BASE_URL,
    baseUrl: `${import.meta.env.AUTH_BASE_URL}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

Create the catch-all route

Create src/pages/api/theauth/[...path].ts. The [...path] spread catches every sub-path under /api/theauth/.

// src/pages/api/theauth/[...path].ts
import { theAuthAstro } from '@glinr/theauth-astro';
import { theauth, mcp } from '@/lib/theauth';

// Who may call the management routes. Return { id } to allow, null to reject (401).
// resolveUser needs an auth.adapter; with only auth.session, omit authenticate
// and any valid session is accepted.
const authenticate = async (request: Request) => {
  const user = await theauth.auth.resolveUser(request);
  return user ? { id: user.id } : null;
};

const handlers = theAuthAstro(theauth, { mcp, authenticate });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;

Or use the ALL handler to catch every HTTP method in one export:

export const ALL = handlers.ALL;

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

interface AuthAstroOptions {
  mcp?: McpAuthModule;     // enables MCP OAuth 2.1 endpoints
  basePath?: string;       // defaults to '/api/theauth'
}

MCP endpoints

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

GET  /api/theauth/.well-known/oauth-authorization-server
GET  /api/theauth/.well-known/oauth-protected-resource
POST /api/theauth/mcp/register
GET  /api/theauth/mcp/authorize
POST /api/theauth/mcp/token

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.

const handlers = theAuthAstro(theauth, { authenticate, trustedProxy: { trustedProxyCount: 1 } });

On Cloudflare use trustedHeader: 'cf-connecting-ip'. Only trust a header your edge overwrites.

Endpoint reference

Method	Path	Description
`POST`	`/agents`	Create an agent
`GET`	`/agents`	List agents
`GET`	`/agents/:id`	Get an agent
`PATCH`	`/agents/:id`	Update an agent
`DELETE`	`/agents/:id`	Revoke an agent
`POST`	`/agents/:id/rotate`	Rotate token
`POST`	`/authorize`	Authorize by agent ID
`POST`	`/authorize/token`	Authorize by bearer token
`POST`	`/delegations`	Create delegation
`GET`	`/delegations/:agentId`	List delegation chains
`DELETE`	`/delegations/:id`	Revoke delegation
`GET`	`/audit`	Query audit logs
`GET`	`/audit/export`	Export audit logs

Full example

// src/pages/api/theauth/[...path].ts
import { createTheAuth } from '@glinr/theauth';
import { createMcpModule } from '@glinr/theauth/mcp';
import { mcpStore } from './mcp-store'; // storage callbacks, see the MCP page
import { theAuthAstro } from '@glinr/theauth-astro';

const theauth = await createTheAuth({
  database: { provider: 'postgres', url: import.meta.env.DATABASE_URL },
  baseUrl: import.meta.env.AUTH_BASE_URL,
  mcp: { enabled: true }, // creates the MCP tables
});

// baseUrl is the public origin plus the adapter mount path (default /api/theauth)
const mcp = createMcpModule({
  config: {
    enabled: true,
    issuer: import.meta.env.AUTH_BASE_URL,
    baseUrl: `${import.meta.env.AUTH_BASE_URL}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

// Who may call the management routes. Return { id } to allow, null to reject (401).
// resolveUser needs an auth.adapter; with only auth.session, omit authenticate
// and any valid session is accepted.
const authenticate = async (request: Request) => {
  const user = await theauth.auth.resolveUser(request);
  return user ? { id: user.id } : null;
};

const handlers = theAuthAstro(theauth, { mcp, authenticate });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;

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.

MCP and gateway

Framework adapters

Client SDKs

Infra

Install

Setup

Options

MCP endpoints

Management routes and client IP

Endpoint reference

Full example

Adapters overview

SvelteKit

Next.js

MCP

​Install

​Setup

​Options

​MCP endpoints

​Management routes and client IP

​Endpoint reference

​Full example

​Related

Adapters overview

SvelteKit

Next.js

MCP

Install

Setup

Options

MCP endpoints

Management routes and client IP

Endpoint reference

Full example

Related