Skip to main content
Building in Go? See the theAuth Go library docs.
theAuth does two jobs, and you can use either one alone or both together. Pick the track that matches what you are building. Each takes under five minutes and the code runs as pasted (SQLite, no other services).

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.
Want a full app instead? 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 mounts the theAuth handler, theAuth issues a session cookie, and protected routes read that session.

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
After you install and start the server:
server log
The curl from step 3 returns the demo agent:
response
The same call without the 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 in theauth_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
The token is shown once, at creation. Store it in your secrets manager or hand it straight to the agent. It cannot be recovered, only rotated.
New agent tokens start with 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:
4

Authorize an action and read the audit trail

authorize returns { allowed, reason?, auditId }. reason explains a denial. Budget policies are not checked here; call theauth.policies.checkBudget() yourself if you use them.
agent.ts
Run it with npx tsx agent.ts.

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.
1

Install

terminal
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 standard Request objects, so you can call it directly or mount it with a framework adapter.
human.ts
Run it with 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.
4

Give the user an agent

The sign-in response contains user.id. Pass it as ownerId in Track A and the foreign key is satisfied with no manual seeding.
human.ts
Prefer to keep Clerk, Auth.js, better-auth or your own login? Skip Track B and pass your user ID as 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 a maxDepth (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.
Bind a D1 database in your wrangler.toml:
Run 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 the emailPassword config, sign-in requires email verification by default and fails with EMAIL_NOT_VERIFIED (HTTP 403). Either:
  1. Post the token from the verification email (the one passed to your sendVerificationEmail callback) to /auth/email/verify
  2. Set requireVerification: false in the emailPassword config (development only)

“FOREIGN KEY constraint failed” when creating agents

The ownerId 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 in localStorage. 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.
Last modified on October 19, 2026