Building in Go? See the theAuth Go library docs.
Add agent auth
Identity, scoped permissions, delegation and an audit row for every AI agent.
Add human auth
Sign-up, sign-in, email verification and password reset for your users.
pnpm create @glinr/theauth-app scaffolds a Next.js SaaS, a Hono MCP server or a Cloudflare Worker with theAuth wired up (also npm create, yarn create, bun create). The CLI asks for a directory, a template, a package manager and a database driver. It writes a .env with generated secrets and adds a doctor script. The generated code creates the owner with theauth.user.create and stores data in a SQLite file. The Hono MCP template still keeps MCP clients, codes and tokens in memory, because database backed MCP stores are not available yet.

Your app, the theAuth handler, a session cookie and a protected route.
Fastest start: theauth init
In an existing project,theauth init writes a working server, creates the owner user and a demo agent, and prints the next steps. It reads package.json to pick the framework (Hono, Express, Fastify, Next.js, SvelteKit or Nuxt) and the package manager, and it stores data in a SQLite file so it survives restarts.
terminal
output
server log
response
Authorization header answers 401. The seed creates the owner with theauth.user.create before the agent, so the foreign key on owner_id holds. Running init again skips every file that exists, so it never overwrites your edits (pass --force to replace the generated files; .env is only ever created). See CLI tools for every flag. The two tracks below show the same calls by hand.
Track A: add agent auth
1
Install
terminal
npm install and yarn add work the same way. The Node SQLite driver is better-sqlite3; on Bun, Deno and Workers use the matching database provider.The unscoped theauth package is an alias for @glinr/theauth-cli, so npx theauth init sets up agent identity and MCP OAuth 2.1 without a separate CLI install. To keep the command on your PATH, install it globally with npm install -g theauth.2
Create an instance and an owner
Every agent has an owner: a user ID that exists as a row intheauth_users (the owner_id column is a foreign key, so creating an agent for an unknown ID fails). Human auth in the next track creates these rows for you; if you already have users in another system, call theauth.user.create() for each one you want to own agents. It validates and lowercases the email, and returns the existing row if the email is already registered.agent.ts
3
Create an agent
agent.ts
ta_. Tokens issued by earlier versions start with kv_ (the old Kavach name) and keep working until you rotate them (see RENAME-MAP.md).There are three agent types:Track B: add human auth
theAuth ships 14 human auth methods and 48 OAuth providers as plugins and modules; this track uses email and password, the most common starting point. See Authentication for the rest.2
Turn on email and password
emailPassword is part of core. It serves POST /auth/email/sign-up, /auth/email/sign-in, /auth/email/verify, /auth/email/resend-verification, /auth/email/forgot-password, /auth/email/reset-password and /auth/email/change-password from the same handler as everything else. You supply the email transport; the callbacks below just log. Passwords are hashed before storage, and sessions are the same sessions the rest of theAuth reads.human.ts
3
Sign up, verify and sign in
The handler takes standardRequest objects, so you can call it directly or mount it with a framework adapter.human.ts
npx tsx human.ts. The browser clients take emailPassword: true and call the same routes (React, Vue, Svelte, Expo, Electron). Details, the error codes and what the routes reveal are on Email and password.ownerId, or wrap your resolver with customAuth (details).
Delegation
An orchestrator agent can delegate a subset of its permissions to a sub-agent. The delegation has its own expiry and amaxDepth (default 3) to prevent unbounded chains: the new link’s depth must be less than or equal to maxDepth.
An agent cannot delegate permissions it does not hold itself. Attempts to escalate are rejected at the point of delegation, not at authorization time.
Full working example
Cloudflare Workers
theAuth runs on Workers with no changes. Pass a D1 binding as the database and use the Hono adapter.wrangler.toml:
npx wrangler d1 execute theauth --file=./theauth-schema.sql to apply the schema yourself (and set skipMigrations: true inside database), or leave it at its default of false and theAuth creates the tables with CREATE TABLE IF NOT EXISTS on startup.
createTheAuth is always async, not only with D1. Workers and Deno both support top-level await, so you can also initialize outside the handler if you use a module worker.Troubleshooting
”Email address has not been verified” after sign-up
With theemailPassword config, sign-in requires email verification by default and fails with EMAIL_NOT_VERIFIED (HTTP 403). Either:
- Post the token from the verification email (the one passed to your
sendVerificationEmailcallback) to/auth/email/verify - Set
requireVerification: falsein theemailPasswordconfig (development only)
“FOREIGN KEY constraint failed” when creating agents
TheownerId must match a row in theauth_users. Sign the user up with emailPassword (Track B), or create one with theauth.user.create() as shown in step 2 of Track A.
Session not persisting after page reload
The React hooks store sessions inlocalStorage. Make sure your app is wrapped in <TheAuthProvider>. If using SSR (Next.js), wrap the provider in a "use client" component.
Next steps
Permission engine
Wildcards, rate limits, time windows, IP allowlists, approval gates.
Delegation chains
Sub-agent delegation with depth limits and cascading revocation.
MCP OAuth 2.1
Set up the authorization server for MCP tool servers.
Framework adapters
Drop-in middleware for ten frameworks.
Coming from another library
Migration guides from better-auth and Clerk.
Configuration
All
createTheAuth() options and environment patterns.