Skip to main content
theAuthHono(theauth, options?) returns a Hono app instance with all theAuth routes pre-mounted. Use app.route to attach it to your main app.

Install

Setup

1

Create the theauth instance

Create this once and reuse it across your app (e.g. lib/theauth.ts):
2

Mount the adapter

Authentication and mount prefixes

theAuthHono refuses to start without a way to authenticate callers on /agents, /delegations, /audit, /dashboard and POST /authorize. Pass authenticate, configure auth.session, or set allowUnauthenticated: true for local development. The full rules and the upgrade note are on the adapters overview.
Plugin routes (magic link, email OTP and so on) work under any prefix. The adapter works out the prefix from the request path, so app.route('/x', theAuthHono(...)) and app.route('/api/v1/theauth', ...) both reach /auth/magic-link/send at the right place.

MCP endpoints

Pass mcp to enable the full MCP OAuth 2.1 authorization server. All MCP endpoints are mounted under the same /api/theauth prefix alongside the REST API:
MCP routes include CORS headers (Access-Control-Allow-Origin: *) and respond to OPTIONS preflight requests automatically.

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

Every adapter serves the same routes with the same status codes. See the route reference.

Protect a route for agents

Missing or invalid bearer token returns 401 and a denied scope returns 403. The body is { "error": { "code", "message" } }, where code is the decision code (for example no_permission). See the requireScope guide.

Full example

Adapters overview

Compare all available framework adapters and their mount patterns.

Fastify

Plugin-based Node.js adapter for high-throughput apps.

Express

Router-based adapter for Express apps.

MCP

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