Skip to main content
theAuthNuxt(theauth, options?) returns an H3 EventHandler. Mount it in a catch-all server route so all theAuth paths are handled.

Install

Setup

1

Create the theauth instance

Create this outside the event handler so it is initialized once at server startup:
2

Create the catch-all route

In Nuxt, a file named [...].ts in the server routes directory catches all sub-paths. Create server/api/theauth/[...].ts:
The basePath option defaults to /api/theauth. If your Nuxt app uses a different route prefix, pass basePath to match.

Options

theAuthNuxt(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 event.context.agent. Pass clientIp to feed ipAllowlist constraints.

MCP endpoints

When mcp is passed, the MCP OAuth 2.1 authorization server is 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

All theAuth routes are then available at /api/theauth/... within your Nuxt server.

Adapters overview

Compare all available framework adapters and their mount patterns.

SvelteKit

Similar catch-all pattern for SvelteKit server 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