Skip to main content
You already have users. You just added agents. This is the ten-minute recipe.
theAuth does not replace your human auth. It runs alongside it. This guide assumes you already have a way to get a stable userId for every request.
Your app mounts the theAuth handler, theAuth issues a session cookie, and protected routes read that session.

What you are adding: one handler, one session, one protected route.

What you need before you start

A user ID on every request

Your existing auth must expose a stable string ID, anything from Clerk’s userId, Auth.js’s session.user.id, or a row id from your own users table. theAuth needs a matching row in its theauth_users table (see step 4).

A database

Postgres, MySQL, SQLite, or Cloudflare D1. theAuth creates its own tables, prefixed theauth_, alongside yours.
Want the files below generated for you? Run npx theauth init --framework nextjs (or hono, express, fastify, sveltekit, nuxt) in your project. It writes src/theauth.ts, a seed script that creates the owner user and a demo agent, the route file, and a .env with generated secrets, then prints the install command for your package manager and a curl against the mounted routes. For Next.js it detects an existing src/ folder and writes src/app/api/theauth/[...theauth]/route.ts (or app/... without one):
npx theauth init --yes (Next.js, pnpm)
The generated authenticate checks a bearer ADMIN_API_KEY. In an app that already has human auth, replace it with your own check as shown in step 3. Re-running init never overwrites a file that exists.

Steps

1

Install

Substitute the adapter for your framework: @glinr/theauth-hono, @glinr/theauth-express, @glinr/theauth-fastify, and so on. See Framework adapters.
2

Create the theAuth instance

lib/theauth.ts
The singleton makes sure the instance (and its database connection) is created once per process. Passing agents is what makes theAuth create the agent, permission, delegation, and audit tables; without it those tables do not exist and agent.create fails.
3

Wire the route handler

app/api/theauth/[...theauth]/route.ts
theAuthNextjs takes the resolved instance (not a function) and returns one handler per HTTP method. Export all five: the REST API uses PATCH and DELETE as well. Its default basePath is /api/theauth; pass { basePath } if you mount it elsewhere. The agent, delegation, audit and dashboard routes require an authenticated caller: pass authenticate (as above), or configure auth.session to accept any signed-in user. With neither, theAuthNextjs throws at startup. See Framework adapters. The authenticate function above is a placeholder; with Clerk or Auth.js, call their server helpers and return { id: userId }.Pick a path that does not collide with your existing auth. /api/theauth/* lives next to /api/auth/* (Clerk / Auth.js) without stepping on it.
4

Create an agent when a user signs up or activates AI features

Hook into your existing post-sign-in flow. For Clerk, that is a webhook or a server action. For Auth.js, the signIn event. For better-auth, the onSignIn hook.
theauth_agents.owner_id is a foreign key to theauth_users.id, and agent.create does not create the user for you. Call theauth.user.create with your provider’s user ID before the first agent. Otherwise the insert fails with a foreign key error. create is idempotent on email, so calling it on every sign-in is safe. If the email already belongs to a different id, it throws USER_EMAIL_CONFLICT instead of returning the wrong row.
wherever you create user-scoped resources
The token is shown once. Store it in your secrets store or hand it directly to the agent process. If you lose it, rotate with theauth.agent.rotate(agentId) to issue a new one. Agents also expire after agents.tokenExpiry (default 24h) unless you pass expiresAt to agent.create.
5

Authorize in your handlers

Anywhere your agent code runs, check authorization before the call.
app/api/agent-action/route.ts

Fitting in with Clerk, Auth.js, and better-auth

Common first-day questions

No by default. theAuth runs its own migrations on first boot. Set skipMigrations: true inside the database config if you want to run them yourself with npx theauth migrate (from @glinr/theauth-cli).
theAuth stores ownerId as a string and never interprets it, but theauth_agents.owner_id references theauth_users.id. Migrating from numeric IDs to UUIDs later means updating theauth_users.id and every referencing owner_id together, in one transaction.
Yes, via event streaming and webhooks. Wire them to your analytics or to Stripe / PostHog / Slack.

Next steps

Permissions

Define what agents can and cannot do.

MCP OAuth 2.1

Run your own authorization server for MCP tools.

Delegation

Let agents spawn sub-agents with scoped permissions.

Audit trail

Query and export every authorization decision.
Last modified on October 18, 2026