Express

theAuthExpress(theauth, options?) returns an Express Router with all theAuth routes pre-mounted. Use app.use to attach it at your chosen path.

Install

pnpm add @glinr/theauth @glinr/theauth-express express
pnpm add -D @types/express

Setup

Create the theauth instance

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

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.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: process.env.AUTH_BASE_URL!,
    baseUrl: `${process.env.AUTH_BASE_URL!}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

Mount the adapter

// src/index.ts
import express from 'express';
import { theAuthExpress } from '@glinr/theauth-express';
import { theauth, mcp } from './lib/theauth.js';

const app = express();

// Required: parse JSON and URL-encoded bodies before the adapter
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// 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;
};

// Mount all TheAuth routes
app.use('/api/theauth', theAuthExpress(theauth, { mcp, authenticate }));

app.listen(3000);

Call express.json() and express.urlencoded() before mounting the adapter. The adapter reads req.body which requires those parsers to be in place.

MCP endpoints

Pass mcp to enable the MCP OAuth 2.1 authorization server. All MCP endpoints are registered on the same router alongside the REST API:

app.use('/api/theauth', theAuthExpress(theauth, { mcp, authenticate }));
// registers:
// 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.

app.use('/api/theauth', theAuthExpress(theauth, { authenticate, trustedProxy: { trustedProxyCount: 1 } }));

On Cloudflare use trustedHeader: 'cf-connecting-ip'. Only trust a header your edge overwrites. Without trustedProxy the adapter uses req.ip, which is the socket peer unless your server framework is configured to trust the proxy.

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

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

const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.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: process.env.AUTH_BASE_URL!,
    baseUrl: `${process.env.AUTH_BASE_URL!}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// 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;
};

app.use('/api/theauth', theAuthExpress(theauth, { mcp, authenticate }));

app.get('/health', (_req, res) => res.json({ ok: true }));

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Adapters overview

Compare all available framework adapters and their mount patterns.

Fastify

High-performance alternative with async plugin architecture.

NestJS

Module-based setup for NestJS apps using Express under the hood.

MCP

OAuth 2.1 authorization server endpoints mounted by the adapter.

MCP and gateway

Framework adapters

Client SDKs

Infra

Install

Setup

MCP endpoints

Management routes and client IP

Endpoint reference

Full example

Adapters overview

Fastify

NestJS

MCP

​Install

​Setup

​MCP endpoints

​Management routes and client IP

​Endpoint reference

​Full example

​Related

Adapters overview

Fastify

NestJS

MCP

Install

Setup

MCP endpoints

Management routes and client IP

Endpoint reference

Full example

Related