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.
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.Steps
1
Install
@glinr/theauth-hono, @glinr/theauth-express, @glinr/theauth-fastify, and so on. See Framework adapters.2
Create the theAuth instance
lib/theauth.ts
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.wherever you create user-scoped resources
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
- Clerk
- Auth.js
- better-auth
Common first-day questions
Do I need to run theAuth migrations manually?
Do I need to run theAuth migrations manually?
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).What if my user IDs change shape later?
What if my user IDs change shape later?
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.Does theAuth emit events I can subscribe to?
Does theAuth emit events I can subscribe to?
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.