Skip to main content
theAuthNextjs(theauth, options?) returns named route handlers { GET, POST, PATCH, DELETE, OPTIONS } for the Next.js App Router. Mount them in a catch-all route file so all theAuth paths are handled.

Install

Setup

1

Create the theauth instance

Create this in a shared module so it is initialized once at server startup:
2

Create the catch-all route

Create app/api/theauth/[...theauth]/route.ts. The [...theauth] segment catches every sub-path under /api/theauth/.
The basePath option defaults to /api/theauth. If you mount at a different path such as /api/auth/theauth, pass basePath: '/api/auth/theauth' so the handler can strip the prefix correctly.

Options

MCP endpoints

When mcp is passed, the following endpoints are available:

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

Do not define createTheAuth inside the route file if you need the instance elsewhere in your app. Export it from lib/theauth.ts and import it where needed to avoid creating multiple instances.

Adapters overview

Compare all available framework adapters and their mount patterns.

Hono

Lightweight edge-compatible adapter for Hono apps.

SvelteKit

Edge-compatible adapter with similar catch-all pattern.

MCP

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