DEV Community: GDS K S

Self-Hosted Vercel Alternative: Git Push to HTTPS on a VPS | Levelrail

GDS K S — Tue, 20 Oct 2026 17:20:44 +0000

Self-Hosted Vercel Alternative: Git Push to HTTPS on a VPS

Levelrail is an open-source, self-hosted alternative to Vercel and Coolify. You install one binary on a Linux server, connect a git provider, and every push builds and deploys your app behind automatic HTTPS, with preview environments for pull requests, logs, metrics and one-command rollback. It uses Apache 2.0, with one edition and no license key.

This post is the hands-on version. I will take you from an empty VPS to a deployed app on its own domain, then tell you plainly what Vercel still does better. I build Levelrail, so read the comparison sections with that in mind.

TL;DR

You want	Levelrail gives you	Where it stops
Deploy on git push	Webhooks from GitHub, GitLab, Bitbucket and Gitea	A native `git push` remote exists but is beta
HTTPS	Built-in Caddy, Let's Encrypt behind one toggle	The default certificate is self-signed until you turn that on
Preview deployments	One per pull request, removed when it closes	Per pull request, not per branch
Rollback	One command, previous images stay pinned	Only while the image still exists
Logs and metrics	Stored on your node, searchable in the dashboard	No visitor analytics
Edge network	None	Put a CDN in front if you need one

What you need

A Linux server with systemd and root access, amd64 or arm64. One vCPU and 1 GB of RAM boots the platform. Plan on 2 vCPU and 2 GB if you build images on the same box, which is where a $5 to $10 VPS starts to matter. Ports 80 and 443 must be reachable from the internet. A domain is optional at first, because Levelrail can hand out a free sslip.io address.

Self-hosted Vercel alternative: install it

Run the installer as root on the server.

curl -fsSL https://levelrail.com/install.sh | sudo sh

It checks the host, installs Docker if it is missing, downloads the newest release and verifies its checksum, starts a levelrail systemd service, and waits until the service is healthy. At the end it prints a dashboard link with a one-time setup token, plus a reminder to back up /var/lib/levelrail-data/master.key. Do that now. That key encrypts every stored secret, and nothing can recover it once you lose it.

Open the link, choose a password, and you are the admin. The install page lists the other options: a container, a pinned version, a source build.

Automatic HTTPS, with one honest caveat

The ingress is Caddy, embedded in the control plane. There is no separate proxy to run. Out of the box every domain gets a certificate from Caddy's internal issuer, so browsers show a warning. That is fine for a first look and wrong for anything public.

The first-run screen has an Enable HTTPS button that needs no DNS. It gives the dashboard a <dashed-ip>.sslip.io name and asks Let's Encrypt for a real certificate. From a terminal, the same thing is:

levelrail-cli settings ingress https enable --wait 2m
levelrail-cli settings ingress https status

Once HTTPS is on, sign in over the https address, because plain HTTP sign-in stops working. For your own domains, switch on real issuance with the Domains page toggle, or:

levelrail-cli settings ingress set --acme-enabled --acme-email you@yourdomain.com

The docs record one live Let's Encrypt run on a public VPS, including what failed before it worked. Renewal and wildcard certificates through DNS-01 are not yet verified in a live run, so check your certificates after the first renewal window. The details are in Domains and ingress.

Deploy from GitHub to your own server

Point the CLI at your first repository. Without --deploy, it only prints a plan: the build method, port, environment variables, volumes and any warnings. Nothing is created.

levelrail-cli import https://github.com/glincker/levelrail
levelrail-cli import https://github.com/glincker/levelrail --deploy --name web

If you are on your laptop rather than the server, run levelrail-cli login --device first. It prints a code that you approve in the dashboard, much like gh auth login. Use levelrail-cli import --help for the full flag list, including --port and --env KEY=VALUE.

Then watch it come up.

levelrail-cli apps status web
levelrail-cli apps logs web --follow
levelrail-cli open web

apps status lists the reconciler's conditions, and each condition carries a reason, so a failed deploy says why instead of retrying silently. A deploy only goes live after the new container passes its readiness probe. If readiness fails, the old container keeps serving.

Environment variables are one command, and --apply redeploys with them.

levelrail-cli env set web DATABASE_URL=postgres://user:pass@host/db --apply

Frameworks that inline variables at build time, such as NEXT_PUBLIC_* in Next.js, need them at build, not just at runtime. The Vercel migration guide walks through that trap.

Make every git push deploy

An import reads a public repository once. To deploy on every push, connect a git provider. This step happens in the dashboard on purpose, because each provider ends in a browser redirect to GitHub, your GitLab instance, Bitbucket or Gitea. For GitHub, open Settings, GitHub App, let Levelrail create the App, and install it on the repositories you choose. GitHub's flow needs a public primary domain, which the HTTPS step above already set.

Then link the repository to your app. This also registers the webhook.

levelrail-cli github-app use-as-source your-org your-app --app-name web --branch main

From now on a push to main builds and deploys. GitLab, Bitbucket and Gitea have matching gitlab-app, bitbucket-app and gitea-app commands. If you would rather deploy only on tags or releases, there is a trigger mode for that, and path filters keep a docs-only commit from rebuilding a service. A git push remote hosted on the server itself exists, but it is beta, so this tutorial sticks to webhooks. See Git integrations.

Add your domain

Create an A record for your domain pointing at the server's public IP, then attach it to the app.

levelrail-cli domains check web app.example.com
levelrail-cli apps domains add web app.example.com

If something does not load, ask the control plane instead of guessing.

levelrail-cli domains diagnose app.example.com

Diagnose runs a fixed list of checks with no AI involved: what three resolvers answer, whether the name points at this server, Cloudflare proxy detection, CAA records that block Let's Encrypt, ports 80 and 443, and the stored certificate. Each failure comes with a fix. Some the platform applies for you, some show the exact DNS record to create. Add --fix to apply the automatic ones. More in the domain doctor docs.

Preview deployments for pull requests

Previews are opt-in per app.

levelrail-cli apps previews enable web
levelrail-cli apps previews list web

With them on, opening a pull request deploys an independent copy named web-pr-<number>, with its own address of the form pr-<number>.<app>.<primary-domain>. New commits redeploy it in place, and closing or merging the pull request removes it. Levelrail posts a status and keeps one comment on the pull request, edited in place, with the preview URL. Previews copy the parent app's environment, and you can override single keys for previews only.

Two limits. Previews are stable on GitHub and beta on GitLab and Bitbucket. Pull requests from forks get no preview until you opt in per app, because a fork's code would run on your server. By default an app can have 10 live previews and the platform 50, with a seven day expiry.

Roll back, and see what happened

levelrail-cli rollback web

That redeploys the previous successful release. Older images stay pinned so cleanup cannot delete a rollback target. Nothing rebuilds from an old commit, so a rollback takes seconds, not a build. Logs and metrics are stored on the node that runs the app, with request rate, errors and latency percentiles per app. The dashboard overlays deploy markers on the charts, so "did that deploy cause this" is a visual question.

Vercel vs Levelrail

	Vercel	Levelrail
Where it runs	A managed cloud	Linux servers you own
Git deploys and previews	Yes	Yes, previews per pull request
Rollback	Instant	One command to a pinned image
Edge network and edge runtime	Yes	No
ISR revalidation	Yes	No
Image optimization	Built in	No
Visitor analytics	Yes	No, request metrics only
Blob and KV storage	Yes	No, managed Postgres and Redis instead
Cost model	Usage and seats	The servers you rent

The full table is on the Vercel comparison page.

What Vercel still does better

If your app leans on the edge, stay. Vercel serves from a global network, runs middleware at the edge, revalidates static pages incrementally and resizes images for you. Levelrail has none of that. It runs your app in containers on the servers you pick, so a visitor far from your VPS pays the latency. A CDN in front of Levelrail closes part of that gap, but it is a part you assemble yourself.

Vercel also has years of production mileage and a team on call. Levelrail's single-server mode is labeled production ready, but multi-node, native git push and the previews for GitLab and Bitbucket are beta. The feature status page shows the evidence behind each label. If you move a real workload, run both for a week and keep DNS ready to switch back.

Where Levelrail wins is the bill. A flat server price does not grow with traffic or seats, and your secrets, logs and metrics stay on machines you control.

Coolify alternative: how Levelrail differs

If you already self-host, the question is usually Coolify. Coolify manages servers over SSH and has the broadest one-click catalog. Levelrail installs an agent on each node that dials out to the control plane over mutual TLS, so managed nodes need no inbound ports, and a reconciler keeps each node converging on its desired state. It ships about 360 templates, though only a sample is deployed end to end in testing.

The move is a read-only import.

levelrail-cli import platform coolify --url "$COOLIFY_URL" --dry-run

The importer reads apps, databases and settings from the old instance and never writes to it. It creates databases and volumes empty, so their contents do not move, and certificates, DNS and deploy history stay behind. Set the source token in APP_IMPORT_SOURCE_TOKEN. Dokploy and CapRover work the same way. See the Coolify migration guide and the side by side comparison.

Try it on your laptop first

You do not need a server to look around. With Docker running and the control plane binary next to the CLI, one command starts a private instance bound to 127.0.0.1, and apps appear at <app>.localhost.

levelrail-cli dev

It serves plain HTTP and is for trying things, not for hosting. When you move to a real server, levelrail-cli doctor runs one health check for Docker, disk, ports, firewall, DNS, certificates, backups and nodes, and levelrail-cli doctor --fix applies the safe fixes after asking you.

Frequently asked questions

Is there a self-hosted Vercel alternative?

Yes. Levelrail covers git deploys, preview environments, HTTPS, logs, metrics and rollback on your own Linux servers. It does not provide an edge network, an edge runtime, ISR or image optimization.

Is Levelrail a Coolify alternative?

It is one. The main differences are an agent that dials out instead of SSH, built-in metrics and log search, and identity features such as OAuth sign-in, IAM policies and an audit log in the free edition.

How much does it cost?

The software is free under Apache 2.0, with no license key. You pay for the server.

Does it work with Next.js?

Yes, as a container built from your Dockerfile. There is no Vercel importer, so you move the settings by hand.

Can I deploy from GitLab, Bitbucket or Gitea?

Yes. All four providers support webhook deploys. Previews are stable on GitHub and beta on GitLab and Bitbucket.

Go deeper

Try it, and star the repo

The install is one command, and the repo is open. A star helps other people find it, and an issue tells me what to fix next.

glincker / levelrail

Free, self-hosted alternative to Vercel, Heroku, Railway, Coolify and Dokku. Push to git, get HTTPS, logs, metrics and one-click rollback on your own servers. One Go binary, no Kubernetes.

Levelrail

The lightweight, self-hosted alternative to Vercel, Heroku, Railway, Coolify and Dokku.
Push to git. Get HTTPS, logs, metrics and one-click rollback on your own servers.
One Go binary · Docker runtime · agents instead of SSH · observability built in · no Kubernetes

Website · Docs · Install · Production ready · Compare · Guides · Roadmap · Changelog · Discussions · Discord

Levelrail is an open source (Apache 2.0) self-hosted PaaS: a Vercel and Heroku alternative that runs on any Linux server you own, from a $5 VPS to a rack. It turns plain servers into a private cloud with Git deploys, automatic HTTPS, databases with verified backups, metrics, logs and alerts, without Kubernetes and without the monitoring stack you would otherwise bolt on.

Install in one command

Needs a Linux server (amd64 or arm64) with systemd and root. Docker is installed for you if…

View on GitHub

Which Vercel feature would stop you from moving a project? Tell me in the comments.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

A deploy platform earns trust on the day something breaks, so I would rather list the gaps up front.

Top 5 Self-Hosted Deployment Platforms in 2026: Coolify, Dokploy, CapRover, Dokku and Levelrail

GDS K S — Tue, 20 Oct 2026 01:35:59 +0000

Top 5 Self-Hosted Deployment Platforms in 2026: Coolify, Dokploy, CapRover, Dokku and Levelrail

Ask five self-hosters which deployment platform to run and you will get five confident answers. Each is right for the person giving it, and that is the problem. The honest answer depends on what you value.

Here is the longer answer. I build one of these tools, Levelrail, and it sits first on this list. Treat that with suspicion. I will show my criteria, I will say who should pick each of the others, and every claim about another project stays inside what its public docs say.

TL;DR

Platform	How it manages servers	Best for
Levelrail	Agent dials out over gRPC with mutual TLS	Built-in metrics, IAM and audit on one binary
Coolify	SSH from the control plane	The broadest one-click catalog
Dokploy	Docker Swarm	Teams that already think in Swarm
CapRover	Docker Swarm	A simple, proven app store setup
Dokku	Commands on the host, via SSH or git push	One server, minimal footprint

Kamal gets an honorable mention below. As a command line tool with no control plane, it fits a different question.

How I ranked them

I weighed five things: how the platform reaches your servers, how it decides a deploy is healthy, what you get without paying, how hard it is to leave, and how honest the project is about its limits. Maturity matters too, and it is where Levelrail loses. It is the youngest project here, and I will keep saying so.

1. Levelrail

Levelrail is an Apache 2.0 platform with one edition and no license key. You install it with one command on a Linux server, and it sets up Docker, a systemd unit and a one-time setup token.

curl -fsSL https://levelrail.com/install.sh | sudo sh

The design choice that matters most is the agent. Each managed node runs an agent that dials out to the control plane with mutual TLS, so the node opens no inbound ports. The agent talks to the Docker Engine API directly and never shells out to the docker CLI. On top of that sits a reconciler: desired state lives in the database, a loop converges the node toward it, and every pass writes a status with a reason.

A deploy counts as healthy only after the new container's readiness probe passes. If readiness fails, the old container keeps serving. Prior images stay pinned, so cleanup cannot delete the one you need for a rollback.

Now the free part. Sign-in with Google, GitHub, Microsoft or any OIDC provider, TOTP, passkeys, IAM policies with Allow and Deny rules, an audit log you can export as CSV, scheduled backups with verification, and deploy approvals all ship in the same binary. Each node keeps its own metrics and searchable logs, and alerts include crashloop detection with the last log lines. An MCP server exposes the same API and permissions to AI agents, and a read-only importer reads a live Coolify, Dokploy or CapRover instance and shows a dry run first.

Pick it if you want an agent-based control plane with observability and access control built in, and you are fine adopting a young project.

Skip it if you need the largest template catalog, a long track record, or a proven SAML setup. Levelrail ships 311 templates and 48 of the top 50 pass its smoke test. Single-server deployments count as production ready, while multi-node and some newer features are still beta. SAML and SCIM exist but are experimental, tested against a local test identity provider only. Public Let's Encrypt passed one live check on a public VPS, and renewal has no live test yet. It runs only on Linux. The latest release is v0.6.0, and the feature status page links the evidence behind every label.

2. Coolify

Coolify has the largest catalog of one-click services and a polished dashboard. It manages servers you already own over plain SSH, with nothing to install on them beyond Docker. It runs as a web application with its own database, uses Docker and Docker Compose per resource, and puts Traefik in front (Caddy is also offered).

Pick it if you want the broadest template list and you are comfortable with SSH-driven management. It has a big community, which means answers to your weird questions already exist.

Skip it if you want managed nodes with no inbound access, or you care about the control plane polling over SSH. Check their docs for the current feature and pricing split, because I have not verified it.

3. Dokploy

Dokploy builds on Docker Swarm, so multi-node scheduling and rolling updates come from a mature, widely understood mechanism. It adds a modern dashboard and Compose support, with Traefik for ingress.

Pick it if Swarm is already how you think about clusters. You get a familiar scheduler with a friendlier face.

Skip it if you want to avoid Swarm. Plenty of teams do, and that is a fair reason.

4. CapRover

CapRover is the veteran. Swarm-based and simple, it comes with a one-click app store and a CLI. It runs as a Swarm service and uses nginx for ingress. It has a large install base and a gentle learning curve.

Pick it if you want something simple that plenty of people have already run for years.

Skip it if you need fine-grained access control or built-in metrics and logs as first-class features. Check their docs, since projects in this space ship quickly.

5. Dokku

Dokku is the classic "Heroku on your own box". You git push to deploy, buildpacks do the build, and a rich plugin ecosystem fills the gaps. With no long-running control service, the idle footprint is almost nothing.

Pick it if you have one server and want the simplest thing that works. On a single host, nothing beats it on simplicity.

Skip it if you want a dashboard-first workflow or a multi-node control plane. Its model is commands on a host.

Honorable mention: Kamal

Kamal is deliberately minimal. It runs over SSH from your machine or CI, pairs with kamal-proxy for zero-downtime cutover, and has no server component at all. If you want the fewest moving parts and do not need a dashboard, it is a strong pick. I left it off the five because it answers a different question: "how do I ship containers" rather than "what platform do I run".

What "free" really covers

This is where the lists usually go quiet, so I will be specific about Levelrail. SSO, audit logs, IAM and backups are not behind a plan. For the other four, I have not verified the current free-versus-paid split, and it changes over time. Open their pricing and licensing pages before you decide. If sign-in, audit logging or fine-grained roles matter to your team, that check is worth ten minutes.

How to choose

Your situation	Look at
One server, simplest possible	Dokku or Kamal
Broadest template list, SSH-only management	Coolify
Docker Swarm is already your model	Dokploy or CapRover
Agent-based control plane with built-in metrics, IAM and audit	Levelrail

If you are already on one of these and wondering about a move, the full comparison covers architecture in detail, and the Coolify alternative and Dokploy alternative pages cover those switches. The importer never touches the old server, so you can try a move without committing to it.

Frequently asked questions

What is the best self-hosted deployment platform in 2026?

No single platform wins. Coolify has the largest catalog, Dokploy and CapRover are Swarm-based, Dokku is the simplest for one server, and Levelrail is the youngest with built-in metrics, IAM and audit. The right pick depends on your server count, your comfort with Swarm and how much you value free access control.

What is a good Coolify alternative?

Dokploy, CapRover and Levelrail are the usual candidates. Levelrail differs by using an agent instead of SSH, and by shipping SSO, audit logs and IAM in its free edition.

What is a good Dokploy alternative?

Coolify and CapRover are close in spirit. Levelrail is the option that avoids Docker Swarm entirely and uses its own agent and reconciler.

Is Levelrail free?

Yes. Levelrail uses Apache 2.0, with one edition, no license key and no paid tier.

Is Levelrail production ready?

Single-server deployments count as production ready. Multi-node and a handful of newer features are still beta. The project is young, so run it beside your current setup for a full business cycle before you move.

Go deeper

Try it, and tell me what I got wrong

Levelrail is open source under Apache 2.0, and every bug report changes what gets built next.

glincker / levelrail

Free, self-hosted alternative to Vercel, Heroku, Railway, Coolify and Dokku. Push to git, get HTTPS, logs, metrics and one-click rollback on your own servers. One Go binary, no Kubernetes.

Levelrail

Website · Docs · Install · Production ready · Compare · Guides · Roadmap · Changelog · Discussions · Discord

Install in one command

Needs a Linux server (amd64 or arm64) with systemd and root. Docker is installed for you if…

View on GitHub

If one of the other four deserves a bigger spot, tell me in the comments and show me the doc that proves it. Which of these would you actually run on a Friday night?

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

A ranking is only worth reading if its author owns up to the row where the bias sits.

Simple Icons alternative with full-color brand logos | theSVG

GDS K S — Thu, 15 Oct 2026 21:37:57 +0000

Full-color brand SVGs for React: thesvg.org · Docs · Library comparison · Star on GitHub

If you need a Simple Icons alternative because every logo comes out as one flat color, use thesvg. It ships the full-color mark for 7,600+ brands, with mono, light, dark and wordmark variants, and it installs as React components, a CDN URL or a CLI. This post shows how to wire full-color logos into React so they also behave in dark mode.

The ticket said "add the integration logos to the settings page." Twelve brands, how hard could it be. I installed the monochrome icon set everyone reaches for, rendered the grid, and sent a screenshot to design. The reply came back in four minutes: "why is everything gray?"

Not gray, exactly. Each logo was one flat color, and Slack, Google and Figma looked like silhouettes of themselves. A single-path icon set can only do that. It cannot ship a brand's real mark.

I build thesvg, which exists to fix this, so everything below uses it and every claim can be checked.

Simple Icons alternatives at a glance

Need	thesvg	Single-path icon sets
Real brand colors	Full-color source files	One flat fill
Dark mode that works	Dark and light variants per brand	Recolor by hand
Wordmark next to the symbol	Wordmark variants	Not provided
Cloud and architecture icons	AWS, Azure, Google Cloud, Kubernetes	Not provided
Install	npm, React, Vue, Svelte, CDN, CLI, API, MCP	npm

For a longer head-to-head with counts and licenses, see the library comparison.

Why Simple Icons is single color

A single-path icon is small and recolors with CSS. It breaks when a mark depends on more than one color to be recognizable. Google, Slack, Microsoft and Chrome are the obvious cases. A gradient is another, and gradients are everywhere in 2026 logo refreshes. You also get no wordmark. A symbol beside a name works in a toolbar, but a partner page usually wants the wide logo.

Check your own brand list

Do not take my word for coverage. List ten brands on your roadmap, not the ones in today's design, and run them through the registry. This script reports which ones exist and which variants each has. It reads the public JSON from the CDN, so nothing needs installing.

const registry =
  "https://cdn.jsdelivr.net/gh/glincker/thesvg@main/src/data/icons.json";
const wanted = ["github", "slack", "stripe", "vercel", "notion"];

const res = await fetch(registry);
const icons: Array<{ slug: string; variants: Record<string, string> }> =
  await res.json();

for (const slug of wanted) {
  const hit = icons.find((i) => i.slug === slug);
  const variants = hit ? Object.keys(hit.variants).join(", ") : "";
  console.log(slug.padEnd(10), hit ? "found" : "missing", variants);
}

Run it with your own list. It takes a minute.

Full-color brand logos in React

Install the React package from thesvg.

npm install @thesvg/react

Import the icons you use, individually, so the bundler keeps only those.

import { Github, Slack, Stripe } from "@thesvg/react";

export function Integrations() {
  return (
    <ul className="grid grid-cols-3 gap-4">
      {[Github, Slack, Stripe].map((Icon, i) => (
        <li key={i}>
          <Icon width={40} height={40} aria-hidden />
        </li>
      ))}
    </ul>
  );
}

Export names follow each brand's slug, so check the package README for the exact one. If you would rather install nothing for a handful of icons, the CDN serves one SVG per URL, which is the quickest way to try it.

<img
  src="https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/github/default.svg"
  width="40"
  height="40"
  alt="GitHub"
/>

Pin a release tag instead of main in production so an upstream change cannot alter a logo under you. The next example does that.

Dark mode for brand logos without a rewrite

The usual failure is a black logo on a near-black card. With variants, the fix is to pick the file by theme rather than recolor.

import { useTheme } from "next-themes";

const CDN = "https://cdn.jsdelivr.net/gh/glincker/thesvg";
const release = "thesvg%403.4.0";

function iconUrl(slug: string, variant: string, ref = release): string {
  return [CDN, "@", ref, "/public/icons/", slug, "/", variant, ".svg"].join("");
}

export function BrandLogo({ slug, size = 40 }: { slug: string; size?: number }) {
  const { resolvedTheme } = useTheme();
  const variant = resolvedTheme === "dark" ? "dark" : "default";

  return (
    <img
      src={iconUrl(slug, variant)}
      width={size}
      height={size}
      alt=""
      loading="lazy"
    />
  );
}

Two caveats. Not every brand ships a dark variant, so check the icon's page or fall back to default.svg on a 404. And the first paint uses the default theme unless you read it on the server, which can cause a one-frame flash.

If you do not need runtime switching, put the logos on a neutral light card in both themes. Most partner pages do that anyway.

Wordmarks and the wide logo problem

The other thing a symbol-only library cannot do is the wide logo. A partner page with six names in a row reads better with wordmarks than with six squares, and mixing the two looks like a mistake.

With variant files you choose per layout, using the same helper from the dark mode example. A compact toolbar takes default.svg. A partner strip takes wordmark.svg, with wordmark-dark.svg and wordmark-light.svg for themed versions.

export function PartnerStrip({ slugs }: { slugs: string[] }) {
  return (
    <ul className="flex flex-wrap items-center gap-8">
      {slugs.map((slug) => (
        <li key={slug}>
          <img
            src={iconUrl(slug, "wordmark")}
            height={28}
            alt=""
            loading="lazy"
          />
        </li>
      ))}
    </ul>
  );
}

Not every brand ships a wordmark. In a strip, a missing wordmark looks worse than a missing logo, so I fall back to the symbol with the brand name beside it.

Frequently asked questions

Is there a Simple Icons alternative with full-color logos?

Yes, thesvg. It has full-color logos for 7,600+ brands with color, mono, light, dark and wordmark variants.

Does Simple Icons support dark mode?

Its icons are single path, so you recolor them with CSS. There is no separate dark artwork, which works for silhouettes and not for multicolor marks.

Can I use full-color brand SVGs commercially?

The file licenses allow it, but trademark rules still apply. Showing a logo to say you integrate with a product is normally fine. Implying a partnership you do not have is not.

How do I get logos for niche developer tools?

Run the coverage script above. thesvg has a submit page if a brand is missing.

The bottom line

The job needed color, and a monochrome set cannot provide it. thesvg gives you the real mark, the dark version and the wordmark from one place, so the question from design never comes back.

If you try thesvg, a star on GitHub helps other developers find it, and the docs cover every package. Which brand could you never find a decent SVG for?

GDS K S · thegdsks.com · building thesvg.org and Glincker · follow on X @thegdsks

Brand logos should be a dependency, not a design chore.

Best free SVG logo library for developers in 2026

GDS K S — Thu, 15 Oct 2026 21:33:43 +0000

thesvg is a free, open source SVG brand logo library. Browse 7,600+ icons · Compare libraries · Star on GitHub · npm

The best free SVG logo library for developers in 2026 is thesvg. It has the largest catalog of brand logos, ships the real full-color mark plus mono, light, dark and wordmark variants, and installs through npm, CDN, CLI, API and an MCP server. The alternatives are narrower: Simple Icons is single color, svgl stops at about 670 brands, and Iconify is an index of other people's sets.

Last month I asked three teammates where they get brand logos for a "trusted by" row. I got three answers: a Figma file nobody owns, a folder of PNGs from Google Images, and "I copy the SVG from the press page." All three had shipped something slightly off. Hunting for logos is the problem a logo library should remove, and one of them does it more completely than the rest.

I build thesvg, so test my claims. Every number below links to a source you can open, and the coverage script further down lets you check your own brand list.

Quick comparison of free SVG logo libraries

Library	Brand logos	Color	License	Install
thesvg	7,600+	Color, mono, light, dark, wordmark	MIT code, brand marks stay trademarks	npm, CDN, CLI, API, MCP
Simple Icons	about 3,400	Single color plus brand hex	CC0	npm, CDN
svgl	about 670	Full color, some light and dark pairs	MIT	Copy from site, API
Iconify	200+ icon sets	Depends on the set	Mixed per set	API, components

Counts come from each project's repository and site as of October 2026. They drift weekly, so check before you quote them.

Why Simple Icons falls short for brand logos

Simple Icons stores every logo as one path in a 24 by 24 box. That works for a silhouette and fails for a brand mark. Slack's four colors and the multicolor Google G arrive as one flat fill, and you recolor them yourself from a hex value. It has about 3,400 brands, no dark artwork and no wordmarks, and some brands were removed at the owner's request, so a name you expect may be missing.

import { siStripe } from "simple-icons";

export function StripeMark({ size = 24 }: { size?: number }) {
  return (
    <svg width={size} height={size} viewBox="0 0 24 24" fill={`#${siStripe.hex}`}>
      <path d={siStripe.path} />
    </svg>
  );
}

That snippet is the whole workflow, and the result is a Stripe mark that is not Stripe's mark.

Why svgl runs out of brands

svgl lists about 670 entries. A product with an integrations page, a status page or a vendor list passes that number quickly, and the gaps land on regional banks, niche developer tools and recent rebrands.

Why Iconify is the wrong tool for logos

Iconify is an index over hundreds of open source icon sets. Quality and licensing vary set by set, so you check each logo yourself, and the brand coverage is whatever the underlying sets happen to hold. It solves loading many icon types through one component. It does not solve getting the right brand mark.

thesvg: the full-color brand logo library

thesvg.org started because I kept needing the full-color mark, a mono version and a wordmark, and no single place had all three. It now lists more than 7,600 icons across brand logos, AWS, Azure and Google Cloud architecture icons, and a Kubernetes set.

Each brand can carry up to seven variants: color, mono, light, dark, wordmark, and themed wordmarks. The variant you want is a file name, not a design task.

npm install thesvg

import github from "thesvg/github";

github.title;     // "GitHub"
github.hex;       // "181717"
github.variants;  // { default: "<svg ...>", mono: "<svg ...>" }

For one file with no install, the CDN path follows a fixed pattern.

<img
  src="https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/github/default.svg"
  width="32"
  height="32"
  alt="GitHub"
/>

The project also ships a CLI (npx @thesvg/cli add github), React, Vue and Svelte packages, a JSON API, and an MCP server so an AI assistant can look icons up instead of guessing a path. Related products are grouped on family pages, such as Google or Microsoft, so you can grab a whole product line at once.

A coverage test you can run in two minutes

Tables of counts only go so far. What matters is whether your brands are in the library. Here is the check I run before committing to one. It reads each project's public data and counts matches for the tools you list.

const wanted = ["github", "stripe", "vercel", "supabase", "clickhouse", "immich"];

const sources = {
  simpleIcons:
    "https://raw.githubusercontent.com/simple-icons/simple-icons/develop/slugs.md",
  svgl: "https://raw.githubusercontent.com/pheralb/svgl/main/src/data/svgs.ts",
  thesvg: "https://cdn.jsdelivr.net/gh/glincker/thesvg@main/src/data/icons.json",
};

for (const [name, url] of Object.entries(sources)) {
  const text = (await (await fetch(url)).text()).toLowerCase();
  const hits = wanted.filter((b) => text.includes(b));
  console.log(name.padEnd(12), `${hits.length}/${wanted.length}`);
}

It is a name match, so treat the result as a first pass and open the site for anything it misses. On a list of 74 developer tools I ran by hand, with the same name matching, thesvg matched 73, Simple Icons about 66 and svgl about 47. Your list will differ, which is the point. Run it on yours.

What to use for which job

For brand logos, use thesvg. That covers a "trusted by" row, an integrations directory, a dashboard that shows whatever tools a customer connects, and architecture diagrams that need AWS, Azure, Google Cloud or Kubernetes icons. The full color mark, the dark version and the wordmark are all there, and the list of brands is not going to run out on you.

If you only need a handful of monochrome social icons in a footer, any single-path set will do. Everything else is a brand logo job.

Are free SVG logos safe to use commercially?

Usually yes for the file, with a caveat that matters. Any library licenses the collection or the code, and none of them can license the trademark. A CC0 or MIT SVG of a logo does not give you the right to imply an endorsement.

Saying "works with Stripe" next to the logo is normally fine. Putting a competitor's mark on a page to look like a partner is not. When it matters, read the brand's own guidelines. thesvg links them from icon pages where a brand publishes them.

Frequently asked questions

What is the best free SVG logo library?

thesvg. It has the largest brand catalog, full-color marks, dark mode variants, wordmarks and every install path from npm to an MCP server.

Which library has the most brand logos?

thesvg lists more than 7,600 icons, Simple Icons about 3,400 and svgl about 670. Counts change often, so check each project's site.

Do I need attribution for these SVG logos?

None of the libraries above require attribution for the file. Brand trademark rules still apply to how you use the logo.

Can I use these with React, Vue or plain HTML?

Yes. Simple Icons and thesvg ship npm packages, thesvg also has React, Vue and Svelte components, and any library on the list works as a plain image from a file or CDN URL.

What to do next

Start with the brands you will need next quarter, not the ones on today's mockup. browse the library. It is MIT licensed and open source, and a star on GitHub helps other developers find it. If a brand is missing, submit it.

Which brand logo did you spend the most time hunting for last time?

GDS K S · thegdsks.com · building thesvg.org and Glincker · follow on X @thegdsks

Stop hunting for brand logos. Use one library that already has them.

theAuth Audit Trails: Compliance Logging for AI Agent Actions

GDS K S — Sat, 10 Oct 2026 22:08:55 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

Picture the question that lands in your inbox six months after launch. "Which of your agents touched customer record 4417 on March 3rd, and who approved it?" If your answer starts with "let me grep the app logs," you already know how the next two days go.

I have been on the receiving end of that kind of question. Agents make it worse than normal services, because an agent decides at runtime what to call. You cannot read the code and know what it did. You need a record written at the moment of each decision.

This guide builds that record from zero. We will use theAuth, an open-source TypeScript library for agent identity and authorization. By the end you will have a log that captures every agent decision, alerts that fire on suspicious behavior, a retention job, a GDPR path for user deletion, and an export you can hand to a reviewer.

I will also tell you what the library does not do. Some of it surprised me when I read the docs closely, and you should hear it before an auditor does.

This is guide 8 of 8 in the theAuth guides. It stands on its own, so you can start right here. It stands alone and pairs well with guides 6 and 7.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions (this guide)	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Goal	What you use	Where it lives
Record every agent decision	`agents.auditAll` (on by default)	Audit trail
Find and filter decisions	`theauth.audit.query()`	Audit trail
Spot odd behavior	Your own queries plus the `onViolation` hook	Anomaly detection
Push alerts out	Webhooks and the SSE event stream	Webhooks
Expire old records	`theauth.audit.cleanup()`	Compliance
Handle deletion requests	The `gdpr` plugin	GDPR data rights
Hand evidence to a reviewer	`audit.export()` or signed credentials	Verifiable credentials

Expect roughly 45 minutes if you already have a Node project. The code runs on SQLite locally and Postgres in production.

Prerequisites

You need Node 20 or newer, a TypeScript project, and the package:

npm install @glinr/theauth

You also need one user ID that exists as a row in the users table. Every agent has an owner, and the owner column is a foreign key. The quickstart shows how to create that row if your auth provider lives elsewhere.

One honesty note before we start. theAuth gives you building blocks for compliance work. It does not make you compliant. The docs say so on three separate pages, and I agree with them. A control mapping is a reporting aid. Your processes, your legal review, and your counsel decide whether you meet an obligation.

Step 1: Create the instance and keep auditAll on

The audit log is a side effect of the permission engine. You do not write log lines by hand. You create the instance, and the engine writes a row each time you call authorize().

import { createTheAuth } from '@glinr/theauth';

export const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  agents: {
    enabled: true,
    maxPerUser: 10,
    auditAll: true, // the default, but I like seeing it written down
    tokenExpiry: '24h',
  },
});

The auditAll flag defaults to true. If you set it to false, the permission engine writes no rows at all, even for denials. That is a sharp edge, so I keep the flag explicit in the config where a reviewer can see it. The configuration reference lists every agent option.

Swap the database block for { provider: 'postgres', url: process.env.DATABASE_URL! } when you deploy. SQLite is fine on a laptop, and Postgres is the right choice once more than one process writes to the log.

Step 2: Give every agent an owner and a narrow grant

An audit entry is only useful if it names someone. Each agent has an ownerId, which becomes the userId on every row it writes. That link is the whole provenance chain: this action, by this agent, owned by this person.

const agent = await theauth.agent.create({
  ownerId: 'user-123',
  name: 'support-summarizer',
  type: 'autonomous',
  permissions: [
    { resource: 'mcp:tickets:*', actions: ['read'] },
    {
      resource: 'mcp:refunds:issue',
      actions: ['execute'],
      constraints: {
        requireApproval: true,
        maxCallsPerHour: 5,
      },
    },
  ],
});

// Shown exactly once. Put it in your secrets manager now.
console.log(agent.token);

Notice the shape of the grants. The agent can read tickets broadly, but the refund action is narrow, rate limited, and gated behind approval. Narrow grants make your log readable. If an agent can do everything, every row looks the same and the log tells you nothing.

The agent token appears once, at creation. theAuth stores only the SHA-256 hash. If you lose the token, you rotate it.

For the approval flow itself, see approval flows. One caveat from the quickstart: with requireApproval: true, authorize() denies until you wire up approval handling. The audit log records that denial like any other.

Step 3: Call authorize before every sensitive action

Now the part that fills the log. Call authorize() before the agent touches anything that matters.

const decision = await theauth.authorize(agent.id, {
  action: 'read',
  resource: 'mcp:tickets:4417',
  arguments: { fields: ['subject', 'status'] },
});

if (!decision.allowed) {
  throw new Error(`Denied: ${decision.reason} (audit ${decision.auditId})`);
}

The returned auditId equals the primary key of the row the engine wrote. Put it in your own application logs, in your trace spans, and in any error you surface. Later, a single ID joins your app logs to the audit trail.

If your service receives the raw bearer token from an incoming request, use authorizeByToken(token, { action, resource }) instead. It writes the same kind of entry.

What a row contains

Each entry carries the agent ID, user ID, action, resource, the parameters you passed, the result, a free-text reason on denials, the evaluation time in milliseconds, and a timestamp. The table also holds the IP address and user agent when the request carried them.

Two details matter for compliance work.

First, the parameters field stores the arguments you pass to authorize(). If you pass a customer's email address or a raw prompt there, it lands in your audit table. That is useful for investigations and a liability for privacy. I pass identifiers and field names, never free text from a user.

Second, the log does not record everything. The docs are explicit that calls rejected before the permission engine runs, such as an unknown or revoked agent, write no row. A revoked agent hammering your API leaves no trace in the audit table. Capture those at your gateway if you need them.

Step 4: Query the log

Everything you need for daily review comes from one method. Filters are optional and combinable, and results come back newest first.

const denials = await theauth.audit.query({
  agentId: agent.id,
  result: 'denied',
  since: new Date(Date.now() - 24 * 3_600_000),
  limit: 100,
});

for (const entry of denials) {
  console.log(entry.timestamp.toISOString(), entry.action, entry.resource, entry.reason);
}

Without a limit, the query returns every matching entry. On a busy table that is a bad day for your memory, so always set one in application code.

One gotcha worth a sticky note: the actions filter runs after limit and offset. A page can come back shorter than the limit you asked for. If you filter on action names, page through results until you get an empty page, and do not treat a short page as the end.

The same data is available over HTTP. The REST API reference documents GET /audit and the export endpoint. Read its warning twice: the adapters do not authenticate callers on most endpoints, including audit queries, so you must put your own authentication in front of the mount path. An open audit endpoint is its own incident.

If you would rather click than query, the admin dashboard has a filterable log viewer with export.

Step 5: Build anomaly detection from the log

Here is the part where I need to be direct. theAuth does not ship an anomaly detector, and the library has no scan() function. The anomaly page lists exactly what exists: a trust score with an anomalyCount factor, the onViolation hook, and a reserved anomaly.detected event name that nothing emits.

That is less than the word "anomaly" suggests, and I would rather you know now. The good news is that the audit log has everything a simple detector needs. Two queries cover most of what I care about.

Denial rate per agent

An agent with a high denial rate is probing, confused, or broken. Each case deserves a look.

export async function highDenialAgents(thresholdPct = 20) {
  const since = new Date(Date.now() - 24 * 3_600_000);
  const logs = await theauth.audit.query({ since, limit: 5000 });

  const byAgent: Record<string, { total: number; denied: number }> = {};
  for (const entry of logs) {
    const bucket = (byAgent[entry.agentId] ??= { total: 0, denied: 0 });
    bucket.total++;
    if (entry.result === 'denied') bucket.denied++;
  }

  return Object.entries(byAgent)
    .filter(([, b]) => b.total > 0 && (b.denied / b.total) * 100 > thresholdPct)
    .map(([agentId, b]) => ({
      agentId,
      denialRate: Math.round((b.denied / b.total) * 100),
    }));
}

I hard-code 20 percent as a default argument here. In your own code, read the threshold from an environment variable, because the right number depends on your traffic.

Call volume per hour

A runaway loop shows up as a spike in calls from one agent. Count the last hour and compare it with a ceiling you choose.

export async function callsLastHour(agentId: string): Promise<number> {
  const recent = await theauth.audit.query({
    agentId,
    since: new Date(Date.now() - 3_600_000),
  });
  return recent.length;
}

Run both from a scheduler every five or ten minutes. A cron job is enough. You do not need a streaming pipeline for this.

Why I do not trust anomalyCount

The trust score counts denied entries whose reason contains INSUFFICIENT_PERMISSIONS, privilege, or escalation. The built-in denial reasons are plain sentences like No permission grants agent "x" access to "write" on "y". None of those words appear, so anomalyCount stays at zero unless your own hook or wrapper writes a reason containing one of them.

Read the score with theauth.trust.computeScore(agent.id) if you want the denial rate factor and the last violation timestamp. Just do not present anomalyCount to an auditor as a privilege escalation detector. The trust scoring page explains how the levels work.

Step 6: Push alerts instead of polling

Queries tell you what happened. Alerts tell you while it happens. theAuth gives you three delivery paths, and they are separate mechanisms with separate event lists.

The onViolation hook

This hook fires for every denial returned by authorize(), with a coarse type such as permission_denied, rate_limited, ip_blocked, time_restricted, or approval_required. The library does not await hooks, and the docs warn that a throw inside one becomes an unhandled rejection. Wrap the body in try/catch.

import { createTheAuth } from '@glinr/theauth';
import { createEventStreamModule } from '@glinr/theauth/auth';

export const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  agents: { enabled: true, auditAll: true },
  hooks: {
    async onViolation({ type, agentId, action, resource, reason }) {
      try {
        stream.emit({
          id: crypto.randomUUID(),
          type: 'anomaly.detected',
          timestamp: new Date(),
          data: { violation: type, action, resource, reason },
          agentId,
        });
      } catch (error) {
        console.error('[audit] violation relay failed', error);
      }
    },
  },
});

const stream = createEventStreamModule({
  db: theauth.db,
  requireAuth: true,
  validateToken: async (token) => {
    const session = await theauth.auth.session?.validate(token);
    return session?.userId ?? null;
  },
});

The hook references stream before the line that creates it. That works because the hook only runs later, after both variables exist. Tidy it to taste.

Remember the warning on the event streaming page: the core never calls stream.emit() for you. Every event reaches the stream because your code emitted it. Here we emit anomaly.detected ourselves, which works even though the library never does.

The SSE event stream

The stream suits live dashboards and security tooling. Clients connect with a bearer token and receive named events. If a client drops, it can pass since to replay what it missed from the theauth_stream_events table.

const source = new EventSource(
  '/api/theauth/events/stream?token=your-token&types=anomaly.detected,agent.revoked',
);

source.addEventListener('anomaly.detected', (event) => {
  const payload = JSON.parse((event as MessageEvent).data);
  console.warn('Violation', payload.data);
});

Two sharp edges here, both from the docs. If you set requireAuth: true and skip validateToken, the module accepts any non-empty token. And automatic browser reconnect replays nothing when your event IDs are UUIDs, because the module parses the Last-Event-ID header as a date. Track the last timestamp yourself and pass since. The full details live on the event streaming page.

The replay table is separate from the audit table. Replay reads stream events, not audit entries, and returns at most 1000 per call, newest first. Do not mistake it for your system of record.

Webhooks for durable delivery

Use webhooks when an external system needs the event, such as a ticketing tool or a SIEM collector. Each endpoint has a URL, a secret, and an explicit event list.

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  webhooks: [
    {
      url: process.env.OPS_WEBHOOK_URL!,
      secret: process.env.THEAUTH_WEBHOOK_SECRET!,
      events: ['agent.revoked', 'agent.rotated'],
      retries: 3,
    },
  ],
});

await theauth.agent.revoke(agent.id);
theauth.webhooks?.emit('agent.revoked', { agentId: agent.id });

The same rule applies: the core does not emit these for you. You call emit after the action. No wildcard exists, and the event list stays closed.

On the receiving side, verify the signature before trusting anything. The signature covers <timestamp>.<raw body>, not the body alone. Reject old timestamps to limit replays.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(
  rawBody: Buffer,
  timestamp: string,
  signature: string,
  secret: string,
): boolean {
  const expected =
    'sha256=' +
    createHmac('sha256', secret).update(`${timestamp}.${rawBody.toString('utf8')}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

Retries use exponential backoff of 1, 2, and 4 seconds. After the last retry, theAuth drops the delivery. It keeps no delivery record and offers no replay, and a process restart loses pending retries. For an audit pipeline, that matters. Treat webhooks as a notification channel, and treat the audit table as the record. If a webhook goes missing, the row still exists. The webhooks page has the full header and retry reference.

Which one when

Use onViolation to react inside your process. Use the stream for people watching a screen. Use webhooks to tell another system. None of them replaces a periodic query against the log, which is the only path with no delivery gap.

Step 7: Set retention on purpose

theAuth never deletes audit rows by itself. Nothing expires. The one deletion path is a method you call:

const { deleted } = await theauth.audit.cleanup({ retentionDays: 365 });
console.log(`Removed ${deleted} audit entries older than 365 days`);

That call permanently deletes rows older than the cutoff. It has no soft delete and no undo.

Pick the number from your obligations, not from disk anxiety. The compliance page notes that the EU AI Act sets its own log retention rules for high-risk systems, and tells you to confirm the period with counsel. I am not a lawyer, and I will not give you a number.

Three rules I follow.

Run cleanup from a scheduled job, never from request handling. Log the deleted count somewhere durable, so the deletion itself leaves evidence. And never run it during a live review or investigation. The compliance page has a warning about exactly that, and you only make that mistake once.

If your database supports partitioning or TTL, that is the better tool at scale. A single DELETE over millions of rows locks things you care about.

Step 8: Handle GDPR requests without breaking the log

Audit logs and privacy law pull in opposite directions. The log wants to remember. A user can ask you to forget. theAuth ships a gdpr plugin for this, and its options are worth understanding before you wire up a delete button.

import { createTheAuth } from '@glinr/theauth';
import { gdpr } from '@glinr/theauth/auth';

const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  agents: { enabled: true },
  plugins: [gdpr()],
});

The plugin registers three endpoints for the signed-in user.

Export

GET /auth/gdpr/export returns a JSON bundle with the user's profile, agents, sessions, audit events, delegations, organization memberships, and API keys. It gives you a summary, not a dump. It leaves out TOTP records, passkeys, OAuth tokens, approval requests, and budget policies, and each section holds summary fields only. Audit events and delegations appear only if the user owns at least one agent.

If your legal team reads "all personal data" literally, this endpoint alone will not meet that bar. You will need to extend it with your own queries.

Delete

DELETE /auth/gdpr/delete removes the account. It requires a literal confirmation string, which keeps accidental calls out.

const res = await fetch('/auth/gdpr/delete', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    confirm: 'delete my account',
    keepAuditLogs: true,
    deleteOrganizations: false,
  }),
});

The keepAuditLogs flag is the audit-versus-privacy dial. When true (the default), theAuth anonymizes audit rows rather than deleting them, so your history of decisions survives without pointing at a named person. When false, theAuth deletes the rows for that user.

Read the details before you rely on it. With keepAuditLogs: true, the agent rows stay with status revoked, and they still carry their name and metadata. If agent names contain personal data, anonymization is incomplete.

The Postgres warning

This one deserves its own heading. The docs state that the module toggles PRAGMA foreign_keys during deletion and audit anonymization. That statement is SQLite syntax. On Postgres or MySQL, the keepAuditLogs: true path and the final user deletion can fail with a database error unless your driver accepts the statement.

I cannot tell you from the docs whether your setup works. I can tell you to test deletion against your production engine, with a throwaway user, before a real request arrives. Do it this week.

Anonymize instead

POST /auth/gdpr/anonymize replaces the email with a deterministic anonymous value and clears the name, external ID, and metadata. It keeps the account row, agents, and audit history. It also removes TOTP records and passkeys. It does not revoke sessions, and it does not touch audit rows.

Choose it when you need referential integrity, for example to keep organization membership intact. Choose deletion when the user wants the account gone.

Finally, deletion is irreversible, and the plugin has no onBeforeDelete hook. Data you store outside theAuth that references the user ID becomes orphaned. Cascade those deletes in your own code first. The GDPR page also shows createGdprModule for background jobs and admin scripts.

Step 9: Export evidence for a reviewer

Eventually someone asks for proof. You have two export paths, and they answer different questions.

Plain JSON or CSV

import { writeFile } from 'node:fs/promises';

const q1 = await theauth.audit.export({
  format: 'json',
  since: new Date('2026-01-01'),
  until: new Date('2026-04-01'),
});

await writeFile('audit-2026-q1.json', q1, 'utf8');

The method returns a string, not a file, so you write it out yourself.

Remember the cap: exports return at most the 10,000 most recent matching entries. A busy quarter will exceed that without warning, and you would hand over a silently truncated record. Export in narrow windows and check the row count against the cap.

export async function exportByDay(start: Date, days: number): Promise<string[]> {
  const files: string[] = [];
  for (let i = 0; i < days; i++) {
    const since = new Date(start.getTime() + i * 86_400_000);
    const until = new Date(since.getTime() + 86_400_000);
    const raw = await theauth.audit.export({ format: 'json', since, until });
    const rows = JSON.parse(raw) as unknown[];
    if (rows.length >= 10_000) {
      throw new Error(`Window ${since.toISOString()} hit the export cap, split it further`);
    }
    files.push(raw);
  }
  return files;
}

Prefer JSON over CSV for anything a machine will parse. In the CSV writer, the writer wraps the reason column in quotes without escaping quotes inside it, and built-in denial reasons contain double quotes. A strict CSV parser can choke. JSON also includes the parameters field, which CSV drops. Neither format includes IP address or user agent, even though the table stores both.

Signed credentials

A JSON file is plain data that anyone could have edited. If a third party needs to check that nobody changed a record since you signed it, export the entries as W3C Verifiable Credentials.

import { exportAuditAsVC } from '@glinr/theauth/vc';
import { generateDidKey } from '@glinr/theauth';

const keyPair = await generateDidKey();
const records = await theauth.audit.query({
  since: new Date('2026-01-01'),
  until: new Date('2026-04-01'),
  limit: 5000,
});

const result = await exportAuditAsVC({
  since: new Date('2026-01-01'),
  until: new Date('2026-04-01'),
  issuerDid: keyPair.did,
  issuerConfig: {
    issuerDid: keyPair.did,
    privateKeyJwk: keyPair.privateKeyJwk,
    publicKeyJwk: keyPair.publicKeyJwk,
  },
  records,
  filter: (r) => r.result === 'denied',
});

console.log(`Signed ${result.count} credentials`);

In production, load a persistent issuer key instead of generating one on each run. Otherwise nobody can verify older exports against a stable DID.

Credentials expire after 24 hours, and the verifier rejects expired ones. Export close to the time you hand evidence over. And be clear about what a signature proves: it shows who signed a record and that it has not changed since. It does not show that the underlying log was complete. The verifiable credentials page covers the presentation output and the JWT format.

Step 10: Map it to the frameworks, carefully

The compliance page maps features to EU AI Act articles, NIST themes, SOC 2 criteria, and ISO 42001. It makes a good starting point for a conversation with your auditor. I would use it like this.

For record-keeping obligations such as EU AI Act Article 12, the audit table gives you automatic, per-decision records with identity, resource, action, parameters, and outcome. For human oversight such as Article 14, requireApproval, delegation depth limits, and revocation give you technical controls. For SOC 2 monitoring criteria, queries and exports give you evidence of review.

What the mapping cannot give you matters more. Tamper-evidence is the clearest gap. The SDK never updates rows, but a database administrator can. The docs recommend database-level audit features or shipping logs to an immutable store. If your auditor asks for tamper-evidence, ship a nightly export to object storage with versioning and retention locks, and keep the signed credential exports for the periods that matter.

Troubleshooting and gotchas

The log is empty after you ran a test. Check auditAll first. With the flag off, the engine writes nothing. Then check that the agent exists and is active, because unknown or revoked agents write no rows.

You get a UUID auditId but find no row. With auditAll: false, the engine still returns an ID without writing a row. Calls blocked by a beforeAuthorize hook, and calls for unknown agents, return an empty auditId.

Your action filter returns half a page. That is the post-pagination filter behavior described in Step 4. Page until empty.

Your export looks short. You hit the 10,000 row cap. Narrow the window.

Revoking an agent did not appear in the log. Revocation is an agent lifecycle change, not an authorization decision. Emit your own event, or record it in your own table, when you revoke.

You wanted to pause an agent and resume it later. Revocation is permanent. Create a new agent with the same configuration instead, and tag the replacement in your own records so the history stays connected.

Webhook signatures never match. You probably hash the parsed body instead of the raw body, or leaving out the timestamp prefix. Use the raw bytes, and join with a dot.

The stream replays nothing after a browser reconnect. Your event IDs are UUIDs. Pass since explicitly.

Deletion fails on Postgres. See the PRAGMA warning in Step 8, and test before you need it.

When this is not the right fit

Four honest limits, so you can decide quickly.

If you need cryptographic tamper-evidence on every row at write time, theAuth does not build that in. You would add a hash chain or an external immutable store.

If you need a ready-made anomaly detector with severity scores and a findings API, theAuth does not provide one. You build it from the queries above or bring a SIEM.

If you need guaranteed delivery of every event to an external system, webhooks drop after retries. Pull from the audit table on a schedule, and reconcile.

If you need a certification, you need an auditor, not a library.

Go deeper

The pages I kept open while writing this:

Audit trail for the entry type, filters, and export options
Compliance for the framework mapping and retention guidance
GDPR data rights for export, delete, and anonymize
Anomaly detection for what exists and what does not
Event streaming for SSE, replay, and connection limits
Webhooks for signing, retries, and the event list
Lifecycle hooks for onViolation and afterAuthorize
Verifiable credentials export for signed evidence
Trust scoring for graduated agent autonomy
Approval flows for human oversight gates
REST API for the HTTP endpoints
Quickstart for the first agent and the first decision

FAQ

Does theAuth log every action an agent takes?

No. It logs every authorization decision that reaches the permission engine, which means every authorize() and authorizeByToken() call against a known agent. If your agent never calls authorize() before acting, nothing gets recorded. The log also skips calls from unknown or revoked agents.

Can I make audit logs tamper-proof?

Not with the SDK alone. It never updates rows, but a database administrator still can. For tamper-evidence, use your database's audit features, ship logs to an immutable store, or export signed Verifiable Credentials for the periods you need to prove.

How long should I keep audit records?

That depends on the rules that apply to your system, and the docs tell you to confirm the period with counsel. The library keeps everything until you call audit.cleanup({ retentionDays }) or expire rows yourself in the database.

What happens to audit rows when a user asks you to delete their data?

With keepAuditLogs: true, the default, theAuth anonymizes the rows and keeps the agents with status revoked. With false, it deletes the user's rows. Test this on your production database engine first, because the module uses a SQLite-specific statement.

Does theAuth detect anomalies automatically?

No. The library ships no detector and no scan() function. You get the onViolation hook, a trust score, and the audit log. You write the detection queries yourself, and the examples above are a starting point.

Can I use this to prove SOC 2 or EU AI Act compliance?

It gives you evidence and a control mapping. It does not give you a certification or a compliance verdict. Treat the exports as inputs to your own process and your auditor's review.

Your turn

Which part of your agent stack would an auditor find hardest to explain today: who owns the agent, what it could do, or what it actually did? I would like to hear where the gap is for you.

Try it yourself

The fastest way in is the quickstart. If this guide saved you time, a star on GitHub helps other developers find the project, and the docs cover every option used above. More about the project lives at theauth.dev.

That is the last guide. Start again at guide 1, or browse the full docs. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

An agent that cannot explain itself later is an agent you will eventually have to turn off.

Secure an MCP Server for Production with theAuth

GDS K S — Sat, 10 Oct 2026 22:06:27 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

Most MCP tutorials stop the moment the demo works. A tool server answers tools/list, the client shows a green dot, and everyone goes home. Then someone puts that server behind a public URL.

I want to walk through what comes after the green dot. Not the OAuth theory, which has plenty of good write-ups. This guide covers the production layers around it: tokens that expire fast, scopes tied to individual tools, argument checks, rate limits, and an audit trail you can query. I will use theAuth, an open-source auth library for AI agents and humans, because I have read its source and docs closely enough to tell you where it stops. Four of those stopping points matter, so I flag each one.

By the end you will have a Hono-based MCP endpoint with six protections, plus a checklist you can paste into a pull request template.

This is guide 7 of 8 in the theAuth guides. It stands on its own, so you can start right here. Guide 5 gives background on agent identities if you want it.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production (this guide)	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Layer	What it does	theAuth piece	Ships today
Identity	OAuth 2.1 with PKCE S256, short-lived tokens	`createMcpModule`	Yes
Scopes	Each tool needs a named scope	`mcp.requireScopes`	Yes
Tool policy	Argument patterns, approval gates, call caps	`theauth.authorize`	Yes
Rate limits	Per-IP on auth routes, per-user on tool calls	`createRateLimiter`	Yes, in memory
Audit	Allow and deny decisions, queryable	`theauth.audit`	Yes
Edge proxy	Auth in front of a server you cannot edit	`@glinr/theauth-gateway`	Yes, agent tokens only

Budget a working session if your database and login page already exist.

Prerequisites

You need Node.js with ESM and top-level await, a Postgres or SQLite database, and a login page that can tell you who the signed-in user is. You also need a 32 character secret for token signing.

I assume you already have an MCP server that speaks JSON-RPC over HTTP. I will refer to its transport handler as handleMcp. Swap in whatever your MCP SDK gives you.

Install the packages:

pnpm add @glinr/theauth @glinr/theauth-hono hono @hono/node-server

If you have never touched theAuth, the quickstart covers the database setup in about six steps. This guide starts after that.

Two kinds of token, and why it matters

Before any code, one distinction saves a day of confusion.

theAuth issues two different bearer credentials. The first is an OAuth access token that the MCP module mints. This HS256 JWT carries a user ID, a client ID, an audience, and scopes. MCP clients like desktop assistants get this one after the user approves access.

The second is an agent token, prefixed kv_. You create it with theauth.agent.create, theAuth stores only its hash, and it maps to a permission list. Scripts and service accounts use it. The agent identity page covers its lifecycle.

Different code checks each one. mcp.requireScopes handles OAuth tokens. The permission engine and the gateway handle agent tokens. I checked the gateway source: it calls theauth.agent.validateToken, so it does not accept OAuth JWTs. Keep that in mind when you reach the proxy section.

Here is the plan. OAuth tokens prove which human approved which client. A service agent holds the permission rules for your tools. Both feed the same audit log.

Step 1: Build the storage callbacks

The MCP module has no database of its own. You hand it callbacks for clients, codes, and tokens. The MCP OAuth page lists them all.

Here is the shape, with in-memory maps so the code runs anywhere. Replace the maps with table reads before you ship.

// lib/mcp-store.ts
import type { McpAccessToken, McpAuthorizationCode, McpClient } from '@glinr/theauth/mcp';

const clients = new Map<string, McpClient>();
const codes = new Map<string, McpAuthorizationCode>();
const tokens = new Map<string, McpAccessToken>();
const byRefreshToken = new Map<string, string>();

export const mcpStore = {
  storeClient: async (client: McpClient) => {
    clients.set(client.clientId, client);
  },
  findClient: async (clientId: string) => clients.get(clientId) ?? null,
  storeAuthorizationCode: async (code: McpAuthorizationCode) => {
    codes.set(code.code, code);
  },
  consumeAuthorizationCode: async (code: string) => {
    const found = codes.get(code) ?? null;
    if (found) codes.delete(code); // single use, always
    return found;
  },
  storeToken: async (token: McpAccessToken) => {
    tokens.set(token.accessToken, token);
    if (token.refreshToken) byRefreshToken.set(token.refreshToken, token.accessToken);
  },
  findTokenByRefreshToken: async (refreshToken: string) => {
    const access = byRefreshToken.get(refreshToken);
    return access ? (tokens.get(access) ?? null) : null;
  },
  revokeToken: async (accessToken: string) => {
    tokens.delete(accessToken);
  },
  resolveUserId: async (request: Request): Promise<string | null> => {
    // Read your own session cookie here. Return null to send the user to loginPage.
    void request;
    return null;
  },
};

Two lines in that file carry the weight. consumeAuthorizationCode must delete the code on read. If it does not, a stolen code works twice. And resolveUserId is the bridge to your login system. Get it wrong and the whole flow authorizes the wrong person.

Step 2: Configure the module for production

Now create the theAuth instance and the MCP module. The defaults are friendly to demos. I change four of them.

// lib/theauth.ts
import { createTheAuth } from '@glinr/theauth';
import { createMcpModule } from '@glinr/theauth/mcp';
import { mcpStore } from './mcp-store.js';

export const MCP_RESOURCE = process.env.MCP_RESOURCE_URL!; // your public MCP origin
const AUTH_BASE_URL = process.env.AUTH_BASE_URL!; // your public auth origin

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: AUTH_BASE_URL,
  mcp: { enabled: true }, // creates the registry tables only
  agents: { enabled: true },
  hooks: {
    async onViolation({ type, agentId, action, resource, reason }) {
      try {
        await sendAlert({ type, agentId, action, resource, reason });
      } catch (error) {
        console.error('[onViolation] alert failed', error);
      }
    },
  },
});

export const mcp = createMcpModule({
  config: {
    enabled: true,
    issuer: AUTH_BASE_URL,
    baseUrl: `${AUTH_BASE_URL}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // 32 characters or more
    scopes: ['mcp:read', 'mcp:write', 'mcp:execute'],
    accessTokenTtl: 900, // 15 minutes instead of 3600
    refreshTokenTtl: 86_400, // 1 day instead of 7
    codeTtl: 120, // 2 minutes instead of 600
    allowedResources: [MCP_RESOURCE],
    loginPage: `${AUTH_BASE_URL}/login`,
    consentPage: `${AUTH_BASE_URL}/consent`,
  },
  ...mcpStore,
});

Why these four?

The access token TTL is the big one. Look at the validation path in the source: it checks signature, issuer, expiry, and scopes. It does not look the token up in your store. A revoked access token keeps working until exp. The TTL becomes your revocation window, and I can defend 15 minutes to a security reviewer. Pick your own, but pick it on purpose.

The code TTL goes down because an authorization code should live for seconds in a healthy flow. Two minutes is generous.

allowedResources pins the audience. With the list set, a client that asks for a resource outside it gets rejected. Without it, any client can ask for a token bound to anything.

consentPage matters because registration is open by design. The MCP spec uses dynamic client registration (RFC 7591), so any client can register itself at /mcp/register. With consentPage configured, the authorization endpoint redirects there instead of issuing a code. Your page then shows the user the client name and scopes, and calls mcp.approveConsent(...) once they agree. Without a consent page, a logged-in user visiting a hostile link gets a code issued with no prompt, as far as I can tell from the docs.

The hooks page explains onViolation. The warning there is worth repeating: that hook is fire and forget, so a throw becomes an unhandled rejection. The try/catch above is not decoration.

Step 3: Mount the routes, including the well-known ones

The Hono adapter mounts everything under a prefix. Pass the module in and it registers the registration, authorization, and token routes. The Hono adapter page has the full list.

// src/index.ts
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { theAuthHono } from '@glinr/theauth-hono';
import { createRateLimiter } from '@glinr/theauth/auth';
import { mcp, theauth } from './lib/theauth.js';

const app = new Hono();

// Throttle the OAuth endpoints by IP. See the rate limit section for why.
const authLimit = createRateLimiter({ max: 30, window: 60 });

app.use('/api/theauth/mcp/*', async (c, next) => {
  const ip = c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown';
  const result = authLimit.check(ip);
  if (!result.allowed) {
    return c.json({ error: { code: 'RATE_LIMITED', message: 'Too many requests' } }, 429, {
      'Retry-After': '60',
    });
  }
  await next();
});

app.route('/api/theauth', theAuthHono(theauth, { mcp }));

// MCP clients look for metadata at the origin root, not under the mount prefix.
app.get('/.well-known/oauth-authorization-server', (c) => c.json(mcp.getMetadata()));
app.get('/.well-known/oauth-protected-resource', (c) => c.json(mcp.getProtectedResourceMetadata()));

The last two routes trip up almost everyone. The adapter registers the metadata documents relative to its mount point, so they live at /api/theauth/.well-known/.... A client that probes /.well-known/oauth-protected-resource at your origin root gets a 404 and gives up. Add the root routes yourself.

The order also matters. In Hono, the middleware must come before the app.route call it should wrap.

Check it from a terminal:

curl -s "$MCP_RESOURCE_URL/.well-known/oauth-protected-resource"

You should see your issuer in authorization_servers and your scopes in scopes_supported. If the response is empty or a 404, fix that before going further.

Step 4: Require a scope per tool

Here is where most guides give you one requireScopes(['mcp:read']) on the whole /mcp route. That treats read_file and run_job the same. They are not the same.

An MCP server on streamable HTTP usually has one endpoint, and the tool name sits inside the JSON-RPC body. You read the body, find the tool, and map it to a scope.

// lib/tool-scopes.ts
export const TOOL_SCOPES: Record<string, string> = {
  list_files: 'mcp:read',
  read_file: 'mcp:read',
  write_file: 'mcp:write',
  run_job: 'mcp:execute',
};

export interface RpcMessage {
  jsonrpc: '2.0';
  id?: string | number;
  method: string;
  params?: { name?: string; arguments?: Record<string, unknown> };
}

/** Scopes a message needs. Returns null for a tool call we do not know. */
export function scopesFor(message: RpcMessage): string[] | null {
  if (message.method !== 'tools/call') return []; // initialize, tools/list, ping
  const name = message.params?.name;
  const scope = name ? TOOL_SCOPES[name] : undefined;
  return scope ? [scope] : null;
}

Unknown tools return null, and the route rejects them. That is deny by default. A tool added next month has no scope until you give it one, which is the behavior you want.

Now the route. It does five jobs in order: parse, check scopes, check the audience, check the per-user limit, then forward.

// src/mcp-route.ts
import type { Context } from 'hono';
import { createRateLimiter } from '@glinr/theauth/auth';
import { MCP_RESOURCE, mcp } from './lib/theauth.js';
import { scopesFor, type RpcMessage } from './lib/tool-scopes.js';
import { authorizeTool } from './lib/tool-policy.js';
import { handleMcp } from './lib/mcp-server.js'; // your MCP transport

const userLimit = createRateLimiter({ max: 120, window: 60 });
const revokedTokenIds = new Set<string>(); // back this with your database

export async function mcpRoute(c: Context): Promise<Response> {
  const text = await c.req.text();
  let parsed: RpcMessage | RpcMessage[];
  try {
    parsed = JSON.parse(text) as RpcMessage | RpcMessage[];
  } catch {
    return c.json({ error: 'invalid_json' }, 400);
  }
  const messages = Array.isArray(parsed) ? parsed : [parsed];

  const needed = new Set<string>();
  for (const message of messages) {
    const scopes = scopesFor(message);
    if (scopes === null) return c.json({ error: 'unknown_tool' }, 403);
    scopes.forEach((scope) => needed.add(scope));
  }

  const check = await mcp.requireScopes(c.req.raw, [...needed]);
  if (!check.authorized) return check.response;
  const session = check.session;

  // The module only checks that an audience exists. Compare it yourself.
  if (session.resource !== MCP_RESOURCE) {
    return c.json({ error: 'invalid_audience' }, 401);
  }
  if (revokedTokenIds.has(session.tokenId)) {
    return c.json({ error: 'token_revoked' }, 401);
  }

  const limit = userLimit.check(session.userId);
  if (!limit.allowed) {
    const wait = Math.max(1, Math.ceil((limit.resetAt.getTime() - Date.now()) / 1000));
    return c.json({ error: 'rate_limited' }, 429, { 'Retry-After': String(wait) });
  }

  const ip = c.req.header('x-forwarded-for')?.split(',')[0]?.trim();
  for (const message of messages) {
    if (message.method !== 'tools/call' || !message.params?.name) continue;
    const decision = await authorizeTool(message.params.name, message.params.arguments ?? {}, ip);
    if (!decision.allowed) {
      return c.json({ error: 'tool_denied', reason: decision.reason }, 403);
    }
  }

  const forwarded = new Request(c.req.url, { method: 'POST', headers: c.req.raw.headers, body: text });
  return handleMcp(forwarded);
}

Three details in that route deserve a closer look.

mcp.requireScopes returns a ready-made response. A missing or bad token gets a 401 with a WWW-Authenticate header that points at your resource metadata. A valid token without the scope gets a 403 with an insufficient_scope challenge and an upgrade URL. Well-behaved clients use that to ask the user for more access. You do not build either response by hand.

The audience comparison is the second detail. The docs are blunt about it: validateToken confirms an audience claim exists and does not compare it with your resource URL. A token minted for a different resource, signed by the same secret, would pass. My two-line check closes that gap. The allowedResources setting from Step 2 limits what clients can request, and the comparison here limits what you accept.

The third is session.tokenId. The session comes from the JWT jti claim. Hold a deny list of those IDs if you need to cut off a token before it expires. It costs one set lookup per call, and it covers the gap the short TTL leaves.

Step 5: Add tool policy with the permission engine

Scopes answer "may this client call write tools at all?" They cannot answer "may it write to this path?" or "is this the 500th call this hour?" The permission engine handles those.

The engine works on agents, so create one service agent that represents your MCP server. Run this once at deploy time, not per request.

// scripts/create-service-agent.ts
import { theauth } from '../src/lib/theauth.js';

const agent = await theauth.agent.create({
  ownerId: process.env.SERVICE_OWNER_USER_ID!, // must be an existing user row
  name: 'files-mcp-server',
  type: 'service',
  expiresAt: new Date(Date.now() + 90 * 24 * 3_600_000), // the default is 24 hours
  permissions: [
    { resource: 'mcp:files:list_files', actions: ['execute'] },
    {
      resource: 'mcp:files:read_file',
      actions: ['execute'],
      constraints: { maxCallsPerHour: 600 },
    },
    {
      resource: 'mcp:files:write_file',
      actions: ['execute'],
      constraints: { allowedArgPatterns: ['^/srv/data/'], maxCallsPerHour: 120 },
    },
    {
      resource: 'mcp:files:run_job',
      actions: ['execute'],
      constraints: { requireApproval: true },
    },
  ],
});

console.error(`Store this agent ID in FILES_MCP_AGENT_ID: ${agent.id}`);

Then the helper the route calls:

// lib/tool-policy.ts
import path from 'node:path';
import { theauth } from './theauth.js';

const AGENT_ID = process.env.FILES_MCP_AGENT_ID!;

export async function authorizeTool(
  tool: string,
  args: Record<string, unknown>,
  ip: string | undefined,
) {
  // Only pass the arguments the patterns should judge. Free text such as
  // file contents would fail a path regex.
  const checked: Record<string, unknown> = {};
  if (typeof args.path === 'string') {
    checked.path = path.posix.normalize(args.path);
  }

  return theauth.authorize(AGENT_ID, {
    action: 'execute',
    resource: `mcp:files:${tool}`,
    arguments: Object.keys(checked).length > 0 ? checked : undefined,
    ip,
  });
}

Now the gotchas, because each one cost me a re-read of the docs.

allowedArgPatterns checks every string value in arguments against every pattern. If you pass content along with path, the content has to match ^/srv/data/ too, and the call fails. That is why the helper forwards only path.

A regex is not a path jail. /srv/data/../../etc/passwd matches ^/srv/data/. The path.posix.normalize call collapses the dots first, so the string the pattern sees is /etc/passwd, which fails. Normalize, then match. If your tools take file paths, also resolve symlinks inside the tool itself. The permission engine sees strings, not the filesystem.

requireApproval: true always denies. The reason text is This action requires human approval before execution, and theAuth ships no approval UI. Your code must show a human the pending call and re-run the check after they agree. The approval flows page describes the pattern. Until you build that, run_job is effectively disabled, which is a safe default.

maxCallsPerHour counts per agent and per concrete resource. Because every user calls through one service agent, all users share that cap. It protects the backend. It does not stop one user from eating everyone's budget, which is why the route also has the per-user limiter.

The engine evaluates only the first matching permission. Order your list from specific to general.

Step 6: Rate limits at three layers

The rate limiting page lists three mechanisms, and it opens with a warning: no single switch exists. I count the layers like this.

The first layer is per IP, on the OAuth endpoints. You saw it in Step 3. I used createRateLimiter rather than the rateLimit() plugin on purpose. The plugin matches paths containing /auth/, such as /auth/sign-in. The MCP routes live under /mcp/*, so I would not assume the plugin covers the token endpoint. Test it against your own mount path before you rely on it.

The second layer is per user on tool calls. That limit sits in the route as userLimit. It keys on session.userId, so a single account cannot flood the server from ten machines.

The third layer is per tool and per resource, from maxCallsPerHour in the permission list. It uses a rolling hour in 5 minute buckets, stored in the database, so every instance shares it.

Layers one and two are in memory. Run three server instances and each keeps its own counter, so your effective limit is three times what you configured. The docs say there is no built-in Redis store. If you scale out, either write your own store or pin rate limiting to a single proxy in front. Know which one you picked.

One more caution. The IP key reads x-forwarded-for. That header is only trustworthy behind a proxy that sets it. Exposed directly, any client can write whatever it likes there and get a fresh bucket per request.

Step 7: Read the audit trail

Every theauth.authorize() call writes one entry, allowed or denied. The audit page has the full field list. Three queries cover most of what I want from it.

Which tools got denied today:

const startOfDay = new Date(new Date().setHours(0, 0, 0, 0));
const denied = await theauth.audit.query({ result: 'denied', since: startOfDay });

const byResource = denied.reduce<Record<string, number>>((acc, entry) => {
  acc[entry.resource] = (acc[entry.resource] ?? 0) + 1;
  return acc;
}, {});

Whether the server is in a runaway loop:

const lastHour = await theauth.audit.query({
  agentId: process.env.FILES_MCP_AGENT_ID!,
  since: new Date(Date.now() - 3_600_000),
});

And a monthly export for whoever asks for evidence:

const csv = await theauth.audit.export({
  format: 'csv',
  since: new Date('2026-09-01'),
  until: new Date('2026-10-01'),
});

Three limits to keep in mind. Exports cap at the 10,000 most recent entries, so page through audit.query for larger ranges. The CSV omits the parameters column; only JSON has it. And retention is on you: theauth.audit.cleanup({ retentionDays }) deletes old rows, and nothing runs it for you.

Now the gap I promised. Because all tool calls run under one service agent, each audit entry names that agent and its owner, not the human who approved the OAuth client. The entry has no field for the end user. Log session.userId, session.clientId, and the returned auditId together in your own structured log at the call site. The auditId joins the two records later.

Also note what is not logged. Requests rejected before the permission engine runs, such as a bad OAuth token or an unknown scope, never reach authorize(). Those 401 and 403 responses come from your route, so count them in your own metrics.

The compliance page maps these records to frameworks like SOC 2 and the EU AI Act. The audit page says plainly that theAuth does not make you compliant on its own. Tamper-evidence needs protection at the database level. I would take that sentence seriously.

Step 8: Put the gateway in front, where it fits

Sometimes you do not own the tool server. It might be a third-party binary, or an internal service nobody wants to touch. The gateway is a reverse proxy for exactly that case.

npx @glinr/theauth-gateway \
  --upstream "$UPSTREAM_URL" \
  --port 4000 \
  --database ./theauth.db \
  --config gateway.json \
  --strip-auth

The --database flag is not optional in practice. The default is :memory:, an empty database, so no token can pass and every request returns 401. Point it at the SQLite file your app uses. The CLI supports SQLite only. For Postgres or MySQL, use embedded mode with createGateway.

A policy file for a server that exposes one path per tool:

{
  "audit": true,
  "rateLimit": { "windowMs": 60000, "max": 300 },
  "policies": [
    {
      "path": "/tools/write-file",
      "method": "POST",
      "requiredPermissions": [{ "resource": "filesystem", "actions": ["write"] }],
      "rateLimit": { "windowMs": 60000, "max": 20 }
    },
    {
      "path": "/tools/**",
      "requiredPermissions": [{ "resource": "mcp", "actions": ["call"] }]
    }
  ]
}

Policies match in order and the first match wins. Put the specific path above the /tools/** catch-all, or the catch-all swallows it.

Be honest about where this stops. Three limits apply, and the first decides whether the gateway fits you at all.

First, policies match on path and HTTP method, not on the JSON-RPC body. If your MCP server uses one /mcp endpoint for every tool, the gateway cannot tell read_file from run_job. For that shape, the in-app checks from Steps 4 and 5 are your tool policy. The gateway still adds token validation and a coarse rate limit.

Second, as covered earlier, it validates agent tokens, not OAuth JWTs from the MCP module. A desktop assistant holding an OAuth token will get a 401 from the gateway. The gateway fits scripts and service agents with kv_ tokens.

Third, its rate limits live in memory, per instance, just like the layers above.

Its audit entries also look different from what you might expect. The gateway has no writer of its own. It calls authorizeByToken with the lowercased method as the action and gateway:<path> as the resource. The recorded result reflects whether the agent holds a matching permission, not whether the gateway let the request through.

Step 9 (optional): Emit agent claims on MCP tokens

If a downstream service wants to know which agent identity sits behind a token, theAuth can embed claims from the IETF agentic JWT draft. You turn it on in the module config with emitAgenticJwtClaims: true and supply getAgenticContext.

Read the standards page before you promise anything to a partner. Only three claims are ever written: agent_id, agent_type, and trust_tier, and only from the values you return. The names on_behalf_of, act, may_act, audit_ref, tool_constraints, wit, and operation exist as constants, but no issuer emits them today. Delegation chains and workload binding are on the roadmap, not in the box.

The hardening checklist

Copy this into your runbook. Each row maps to a step above.

Check	Setting or code	Why
Keep access tokens at 15 minutes or less	`accessTokenTtl: 900`	Checks skip the store, so TTL sets the revocation window
Keep codes at 2 minutes or less	`codeTtl: 120`	Shrinks the theft window
Make codes single use	Delete inside `consumeAuthorizationCode`	A replayed code must fail
Pin resources	`allowedResources`	Clients cannot request arbitrary audiences
Compare the audience	`session.resource === MCP_RESOURCE`	The module only checks that one exists
Turn the consent screen on	`consentPage`	Open registration plus no prompt opens a phishing path
Use a strong signing secret	32 characters or more, from a secret manager	HS256 uses a shared secret
Serve well-known routes at the root	Two `app.get` routes	Clients probe the origin root
Deny unknown tools	`scopesFor` returns `null`	New tools start with no access
Give each tool one scope	`TOOL_SCOPES` map	Read access should not imply execute
Normalize path arguments	`path.posix.normalize` before regex	Dot segments defeat prefix patterns
Gate dangerous tools on approval	`requireApproval: true`	A human sits in the loop
Rate limit auth routes by IP	`createRateLimiter`	Registration and token endpoints face the public
Rate limit tool calls per user	`userLimit` keyed by `userId`	One account cannot drain a shared budget
Plan for scale-out	Custom store or single proxy	Memory counters live per process
Page a human on denials	`onViolation` with `try/catch`	A throwing hook can crash the process
Log the end user next to `auditId`	Your own structured log	The audit row names the service agent
Schedule retention	`audit.cleanup` in a cron job	Nothing deletes rows for you
Plan the service agent expiry	Set `expiresAt`, then rotate	The default lifetime is 24 hours

Troubleshooting and gotchas

Every call returns 401 after login works

Check three things in order. First, the token's iss must equal the issuer in your config, character for character, including a trailing slash. Second, the signingSecret must be identical on every instance that validates tokens. Third, confirm the token has an audience. A client that never sent a resource parameter gets the issuer as its audience, and then your MCP_RESOURCE comparison rejects it.

The client says it cannot find the authorization server

That is the well-known routes under the prefix problem from Step 3. Fetch /.well-known/oauth-protected-resource at your origin root. If you get a 404, add the two root routes.

The metadata lists endpoints that return 404

The authorization server metadata advertises revocation_endpoint and jwks_uri. The TypeScript adapters do not serve either one today. Two consequences follow. Clients cannot revoke a token through a standard endpoint, and a third party cannot verify your tokens from a JWKS document. Tokens use HS256, so any service that checks them needs the shared secret. Plan for that before you hand the secret to another team, and rotate it knowing that rotation invalidates every outstanding token.

Refresh token theft goes unnoticed

Each refresh call revokes the old access token and issues a new pair. The module does not detect reuse of an old refresh token. That logic lives in your findTokenByRefreshToken and revokeToken callbacks. If you want reuse detection, record which refresh tokens you already consumed, and revoke the whole family when one comes back.

The service agent stops working after a day

You left expiresAt at the default of 24 hours. Token validation then flips the agent to expired. Set an explicit expiry, rotate on a schedule with theauth.agent.rotate, and alert before the date.

The docs link for MCP returns an error

A small note from my own link checking. At the time of writing, the bare /mcp path on the docs host answers a plain GET with a 405, while the same path with a .md suffix returns the page as markdown. I suspect the docs host reserves /mcp for its own MCP endpoint. I linked the .md form above so the links in this guide resolve.

Go deeper

The pages I leaned on, in the order I would read them next.

MCP OAuth 2.1 for the full config reference and the metadata documents
Permission engine for every constraint and the matching rules
Rate limiting for the plugin, the limiter, and the permission cap
Audit trail for filters, exports, and retention
Gateway for policies, embedded mode, and Docker sidecars
Standards alignment for what the agentic claims do and do not cover
Lifecycle hooks for beforeAuthorize and onViolation
Approval flows for building the human step
Compliance mapping for audit evidence

FAQ

Do I need OAuth for a local MCP server?

No. A server that runs on the same machine as the client over stdio has no network surface to protect, and OAuth adds friction for no gain. OAuth matters once the server listens on a network address that other people can reach. If you only ever run locally, skip this guide.

Can I use the gateway instead of writing the scope checks?

Only if your tools sit on separate paths and your callers hold agent tokens. The gateway matches on path and method, and it validates kv_ tokens, not OAuth JWTs from the MCP module. For a single-endpoint MCP server with desktop clients, write the checks in your route.

How do I revoke a token right now?

The module serves no revocation endpoint today, and validation does not consult the store. Keep a deny list of token IDs (jti) in your route, as in Step 4. Pair it with a short access token lifetime so the list stays small. For agent tokens, theauth.agent.revoke takes effect immediately and is permanent.

What does the audit log not capture?

It records calls that reach theauth.authorize() or authorizeByToken(). Requests that fail earlier, such as a malformed bearer token or an unknown agent, are not logged by the permission engine. The built-in engine also writes rate limit denials as denied, not rate_limited. Add your own metrics for the early rejections.

Is theAuth the right choice for this?

It fits when you want the OAuth server, permission rules, and audit trail in one TypeScript codebase that you host. It fits less well if you need a JWKS endpoint, asymmetric signing, or a built-in distributed rate limiter, since none of those ship today. An identity provider you already pay for may serve you better if it covers MCP's flow and you only need scopes. Weigh the gaps in this guide against your own needs.

What I would do first

If you do only three things from this list, shorten the token TTL, deny unknown tools, and compare the audience. Each one is a few lines of code, and together they close the three holes I would worry about most.

Which of these layers is missing from the MCP server you run today, and what has stopped you from adding it?

Try it yourself

Next: guide 8, the audit trail. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

Tokens prove who is calling. Scopes, limits, and logs decide what happens next.

theAuth Multi-Tenant SaaS Auth: Orgs, RBAC, SSO, SCIM

GDS K S — Sat, 10 Oct 2026 22:01:47 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

The first enterprise deal usually arrives with one sentence in an email. "Can our employees sign in with Okta, and can you turn them off when they leave?"

I have watched teams answer that sentence with a six-week detour. They bolt a company_id column onto every table, hand-roll invite emails, and then discover that SAML has opinions. This guide walks the whole path in one sitting: organizations, roles, a resource hierarchy, SSO, and SCIM provisioning.

I use theAuth for the code, an open-source TypeScript auth library (@glinr/theauth). I will also tell you where it stops and where your own code has to take over. Some of those gaps matter more than the features.

This is guide 3 of 8 in the theAuth guides. It stands on its own, so you can start right here. It builds on a working login (guide 1) and does not need the other guides.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM (this guide)	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Layer	What it does	theAuth piece	Docs
Tenancy	Groups users into a company	`org` module	Organizations
Roles	Answers "can this member do X in this org"	built-in and custom org roles	Organizations
Resource access	Answers "can this user see this one document"	ReBAC engine	ReBAC
Enterprise login	SAML 2.0 or OIDC, routed by email domain	`sso` module	SSO
Lifecycle	Create and deactivate users from the IdP	`scim` plugin	SCIM

You will end with one createTheAuth call that wires all five layers, plus a short list of checks you must add yourself.

Prerequisites

You need Node, a TypeScript project, and a database. The examples use SQLite so you can run them in a scratch folder. The docs show the same config with provider: 'postgres' for production.

You also need a way to receive HTTP requests. The examples assume you mounted the theAuth adapter at /api/theauth, which is the default mount path in the docs. Any framework works. Adapter setup is outside this guide.

One honest scoping note before we start. If your product only has individual users and no companies, none of this applies. Skip the whole stack and use plain sign-in.

Step 1: Install and create the instance

npm install @glinr/theauth

Start with only the organization module and grow from there. The org key is what creates theauth.org. Without it, that property is null, and every call in the next steps fails.

import { createTheAuth } from '@glinr/theauth';

export const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  org: {
    maxMembers: 100,
    maxOrgsPerUser: 5,
    allowCustomRoles: true,
  },
});

Those three numbers match the defaults in the docs: 100 members per org, 5 orgs per user, custom roles on. I set them in code to document the choice. Read the full option list on the Organizations page.

Step 2: Create an organization

An organization is your tenant in practice. Slugs allow lowercase letters, numbers and single hyphens.

const org = await theauth.org!.create({
  name: 'Acme Corp',
  slug: 'acme-corp',
  ownerId: 'user_abc',
  metadata: { plan: 'pro' },
});

console.log(org.id); // org_...

The ownerId user becomes a member with the owner role automatically. That is one less write for you to forget.

I want to flag a naming trap here. theAuth also has a separate tenant module with theauth.tenant.create. It stores a tenant record, and agents can carry a tenantId. The Multi-tenant page is blunt about it: tenants are a data model, not an enforcement layer. authorize() does not compare tenants, and a suspended tenant does not block anything.

For human members of a SaaS product, I reach for organizations. I treat the tenant module as a label for agents, and I check agent.tenantId myself before acting.

Step 3: Invite members and assign roles

Invitations expire after 7 days by default. You can change that with invitationExpiryMs, and cap invites per org per hour with maxInvitationsPerHour (default 50).

const invitation = await theauth.org!.invite({
  orgId: org.id,
  email: 'alice@acme.com',
  role: 'admin',
  invitedBy: 'user_abc',
});

// Later, in the accept-invite handler for the signed-in user:
const member = await theauth.org!.acceptInvitation(invitation.id, 'user_xyz');

Day-two management is three calls.

const members = await theauth.org!.getMembers(org.id);

await theauth.org!.updateMemberRole(org.id, 'user_xyz', 'member');

await theauth.org!.removeMember(org.id, 'user_xyz');

These methods take user ids as plain arguments, such as invitedBy. Your route handler must confirm that the caller may invite before it calls invite. Step 4 shows the check.

Step 4: Roles and permissions

Four roles ship built in.

Role	Permissions
`owner`	everything, including `org:manage`, `org:delete`, `roles:manage`
`admin`	`members:invite`, `members:remove`, `agents:create`, `agents:revoke`, `agents:manage`
`member`	`agents:create`, `agents:manage`
`viewer`	none

The runtime check is one call. Here is the guard I put in front of the invite route.

export async function canInvite(orgId: string, userId: string): Promise<boolean> {
  return theauth.org!.hasPermission(orgId, userId, 'members:invite');
}

Your product will have domain permissions that the built-ins do not name. A billing role is the classic example. Create it per organization.

await theauth.org!.createRole(org.id, {
  name: 'billing',
  permissions: ['invoices:read', 'invoices:pay'],
});

Then call hasPermission(org.id, userId, 'invoices:pay') in your billing routes. Permission strings are yours to define. theAuth stores them and answers membership questions about them.

Set allowCustomRoles: false if you want every org locked to the four built-ins. I do that for products where support staff need to reason about every account by role name alone.

The HTTP route option

You can also serve organization routes without writing handlers. The organization() plugin registers /auth/org/* routes for your adapter to serve, and every one of them requires an authenticated user.

import { organization } from '@glinr/theauth/auth';

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  auth: { session: { secret: process.env.SESSION_SECRET! } },
  plugins: [organization({ maxMembers: 100, maxOrgsPerUser: 5, allowCustomRoles: true })],
});

The plugin does not add theauth.org to the instance. Pick one style per concern, or pass both org and the plugin if you want the programmatic API and the routes. The route table lives on the Organizations page.

A second route table on that page covers theauth.org.handleRequest. It serves more paths and does no authentication at all. Mount it only behind your own checks.

Step 5: Fine-grained access with ReBAC

Roles answer "what can an admin do in this org". They cannot answer "can Alice open this one document because she edits its workspace". That question needs a graph.

theAuth ships a relationship-based engine for it. You register resources in a tree, then add relationship tuples between subjects and resources.

import { createReBACModule, createDatabase, createTables } from '@glinr/theauth';

const db = await createDatabase({ provider: 'sqlite', url: 'theauth.db' });
await createTables(db, 'sqlite');

const rebac = createReBACModule({}, db);

await rebac.createResource({ id: 'acme', type: 'org' });
await rebac.createResource({ id: 'eng', type: 'workspace', parentId: 'acme', parentType: 'org' });
await rebac.createResource({ id: 'api', type: 'project', parentId: 'eng', parentType: 'workspace' });
await rebac.createResource({ id: 'spec', type: 'document', parentId: 'api', parentType: 'project' });

await rebac.addRelationship({
  subjectType: 'user',
  subjectId: 'alice',
  relation: 'editor',
  objectType: 'workspace',
  objectId: 'eng',
});

const result = await rebac.check({
  subjectType: 'user',
  subjectId: 'alice',
  permission: 'viewer',
  objectType: 'document',
  objectId: 'spec',
});
// result.data.allowed === true

Two rules produce that true. An editor implies viewer. Also, workspace, project and document resources inherit from their parent, so the grant on eng reaches spec, two levels down.

Four details bit me or would have bitten me.

Resource ids are the primary key across all types. A document:spec and a project:spec cannot coexist, so prefix your ids with something unique.

Deleting a resource cascades to its children and to every relationship that names it. That is convenient and also a good reason to confirm before calling it.

The org type does not inherit from a parent. Types missing from the built-in table, such as doc, get no implied relations, so only an exact relation match grants access. Add your own rules with permissionRules for a wiki type.

Methods return a Result with success and data rather than throwing on expected failures such as PARENT_NOT_FOUND. Check success.

You can also list what a user reaches, which powers "shared with me" screens.

const projects = await rebac.listObjects({
  subjectType: 'user',
  subjectId: 'alice',
  permission: 'viewer',
  objectType: 'project',
});
// projects.data = ['api', 'web']

Where ReBAC does and does not connect

Here is a limit worth knowing now. theauth.authorize() does not consult ReBAC. The docs describe the bridge: set relation on a permission and call theauth.policy.evaluate(), which runs the graph check for you.

const decision = await theauth.policy.evaluate({
  subject: { userId: 'usr_alice', orgId: org.id },
  action: 'read',
  resource: 'document:spec',
});

if (!decision.allowed) {
  throw new Error(`Denied: ${decision.reason}`);
}

The policy engine builds its own ReBAC module with the default rules. Your custom permissionRules are not used there. The resource must also be a concrete type:id, so a wildcard never matches a relation. Read the Policy engine page before you plan around this. For user subjects it also folds in org role permissions, scoped by the orgId you pass.

I also keep the cache in mind. The engine caches decisions per process for 60 seconds by default. After you revoke a relationship, call invalidate for that user, and accept that other processes catch up when their entries expire.

Step 6: Add SSO per organization

Now the enterprise part. The sso key takes your provider definitions. SSO has no plugin form, and theauth.sso is null unless you pass the key.

export const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  org: { maxMembers: 100, maxOrgsPerUser: 5, allowCustomRoles: true },
  sso: {
    saml: [
      {
        id: 'okta',
        name: 'Okta',
        entryPoint: process.env.OKTA_SSO_URL!,
        issuer: process.env.APP_URL!,
        cert: process.env.OKTA_SAML_CERT!,
        callbackUrl: `${process.env.APP_URL}/api/theauth/auth/sso/saml/conn_id/acs`,
      },
    ],
    oidc: [
      {
        id: 'azure',
        name: 'Azure AD',
        issuer: process.env.AZURE_ISSUER!,
        clientId: process.env.AZURE_CLIENT_ID!,
        clientSecret: process.env.AZURE_CLIENT_SECRET!,
        callbackUrl: `${process.env.APP_URL}/api/theauth/auth/sso/oidc/conn_id/callback`,
        scopes: ['openid', 'profile', 'email'],
      },
    ],
  },
});

A provider definition is a template. A connection ties one provider to one organization and one email domain.

const connection = await theauth.sso!.createConnection({
  orgId: org.id,
  providerId: 'okta',
  type: 'saml',
  domain: 'acme.com',
});

// On the login page, after the user types an email:
const conn = await theauth.sso!.getConnectionByDomain('acme.com');

That getConnectionByDomain call is the heart of the "enter your work email" screen. If it returns a connection, you redirect to the IdP. If it returns nothing, you show the normal sign-in form.

The SAML flow

// 1. Send the browser to the IdP
const authUrl = await theauth.sso!.getSamlAuthUrl(connection.id, '/dashboard');

// 2. Handle the POST the IdP sends to your ACS URL
const { user, orgId } = await theauth.sso!.handleSamlResponse(
  connection.id,
  samlResponseFromFormData,
);

The module verifies the response against the IdP certificate. The module rejects unsigned responses unless you set wantAuthnResponseSigned: false, and I would not. It does not support encrypted assertions, so ask the customer's IT admin for unencrypted ones. That request comes up in real onboarding calls, so put it in your setup doc.

Pass expectedRequestId as a third argument to bind the response to a request you started.

The OIDC flow

const state = theauth.sso!.generateState();
const authUrl = await theauth.sso!.getOidcAuthUrl(connection.id, state);
// redirect the browser to authUrl

// In the callback route, after you validate the state:
const { user, orgId } = await theauth.sso!.handleOidcCallback(connection.id, codeFromQuery);

Discovery runs automatically from issuer/.well-known/openid-configuration, and the module verifies the id_token against the IdP's JWKS. It rejects an id_token without an email claim. Use validateState on the way back, and pass a nonce through both calls if you want replay protection.

The default rate limit is 10 attempts per connection per 60 seconds, tunable with rateLimitMax and rateLimitWindowSeconds. Failed logins return 401, or 429 when limited.

Step 7: Finish the login yourself

Demos skip this step. It cost me the most time, and nobody warned me.

The SSO module does not create a user row. It does not add a membership. It does not issue a session. It hands you a verified identity, { user: { id, email, name? }, orgId }, and stops.

The user.id is deterministic: saml_ plus a SHA-256 hash of providerId:email for SAML, and oidc_ plus a hash of providerId:sub for OIDC. The same person always maps to the same ID. But that ID is not a row in your users table.

Your callback owns three jobs: find or create your user, ensure the org membership, and start a session. Here is the shape I use for the middle one. The findOrCreateUser and startSession helpers are yours, not theAuth's.

export async function completeSsoLogin(identity: {
  user: { id: string; email: string; name?: string };
  orgId: string;
}) {
  const localUser = await findOrCreateUser(identity.user.email, identity.user.name);

  const members = await theauth.org!.getMembers(identity.orgId);
  const isMember = members.some((m) => m.userId === localUser.id);

  if (!isMember) {
    await theauth.org!.addMember(identity.orgId, localUser.id, 'member');
  }

  return startSession(localUser.id);
}

Two notes on that code. addMember is on the module in the package source, though the docs page lists it only as an HTTP route, so confirm the signature in your installed version. And auto-joining everyone who authenticates through a connection is a policy choice. For a connection tied to acme.com it is usually right, because the IdP already vouched for the person.

Pass onAuditEvent in the sso config if you want login success and failure events delivered to your own logging.

Step 8: Add SCIM for provisioning

SSO decides who can sign in. SCIM decides who exists. Without it, an employee who leaves the company keeps their account until someone remembers to clean up.

SCIM is a plugin from the auth entry point.

import { scim } from '@glinr/theauth/auth';

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  org: { maxMembers: 100, maxOrgsPerUser: 5, allowCustomRoles: true },
  plugins: [
    scim({
      bearerToken: process.env.SCIM_TOKEN!,
    }),
  ],
});

Then point the IdP's provisioning settings at your server.

Base URL:  <your app origin>/api/theauth/scim/v2
Auth:      Bearer token
Token:     <your SCIM_TOKEN>

Use a random secret of at least 32 bytes. The /api/theauth segment follows wherever you mounted the adapter.

The plugin exposes the standard SCIM 2.0 Users and Groups endpoints (list, get, create, replace, patch, delete). Users map to the theAuth users table. Groups map to organizations, which is why the earlier org work pays off here. Discovery lives at ServiceProviderConfig, Schemas and ResourceTypes.

The plugin also accepts autoCreateUsers and autoDeactivateUsers (both default true), plus onProvision(user) and onDeprovision(userId) callbacks. The callbacks are where I sync SCIM events into my own tables.

What the server supports

Filtering covers the RFC 7644 grammar through the filter query parameter, with operators eq, ne, co, sw, ew, gt, ge, lt, le and pr. A request like this works.

GET /scim/v2/Users?filter=userName eq "john@example.com"

A filter that does not parse returns 400 invalidFilter. The filter reference has the grammar, and the PATCH reference covers path expressions and the 1000-operation cap per request.

Not every SCIM feature ships. POST /scim/v2/Bulk returns a spec-compliant 501, and the config advertises bulk as unsupported. GET /scim/v2/Me returns 501 unless you pass a resolveSelf callback. IdPs that depend on bulk will need a different path.

The deprovisioning gap

Read this part twice. A DELETE, or active: false in a PUT or PATCH, deactivates a user by setting the banned flag and a scim:deprovisioned metadata marker. That happens when autoDeactivateUsers is on.

theAuth's sign-in modules do not check the banned flag.

That means SCIM deprovisioning does nothing to a user's access until you add a check. Put it in your session start path.

export async function startSession(userId: string) {
  const user = await loadUser(userId); // your own query
  if (user.banned) {
    throw new Error('Account deactivated');
  }
  // ...issue the session
}

The Admin page covers the manual user-management tools that sit next to this. Do the same check in any long-lived session refresh too, or a deprovisioned user keeps working until the token expires.

Troubleshooting and gotchas

Here are the failures I would expect in the first week, grouped by symptom.

The org property is null

You did not pass the org config object, or you only registered the organization() plugin. The plugin serves HTTP routes and does not create the programmatic object. Pass the org key.

The sso property is null

Same cause, different key. Add sso to the config. No plugin form exists.

SAML login fails with a signature error

Check three things. Use the IdP signing certificate for cert. Make your IdP sign the response (disabling that check is a bad idea). Send assertions unencrypted, since the module does not support encrypted ones.

OIDC rejects a valid login

The usual cause is a missing email claim in the id_token. Add the email scope and confirm the IdP releases the claim. The module rejects tokens without one.

Everyone is rate limited during a rollout

The SSO default is 10 attempts per connection per 60 seconds. A whole office signing in at 9:00 can hit that. Raise rateLimitMax and watch the 429 rate.

A removed employee can still sign in

Almost always the banned gap above. SCIM set the flag, and nothing read it. Add the check in your session start path and in session refresh.

SCIM returns 401

The Authorization: Bearer value must match SCIM_TOKEN exactly. The docs describe a single static secret compared as-is, so no per-customer token exists. Every customer's IdP uses the same value. If one leaks, you rotate it and update all of them. That is a real operational cost, and a reason to think twice if you expect hundreds of SCIM customers.

Cross-tenant data shows up in a list

This one is your code, not the library. Neither the tenant module nor the REST endpoints filter your own tables by organization. Every query you write needs an org_id predicate, and I would add a test that fails when one is missing.

When this is not the right fit

I would not use this stack in three situations.

If you need hard, enforced tenant isolation from the library itself, with suspension that blocks access, theAuth does not ship that today. You would build it around the tenant and org modules.

If your enterprise buyers require SCIM Bulk operations, the server returns 501.

If you need per-tenant SCIM credentials, the single static token will not meet that.

None of these are dealbreakers for an early B2B product. They matter more once the contracts get large.

Go deeper

The docs pages behind each step, in the order I would read them:

Organizations for the full config reference and both route tables
Multi-tenant isolation for the tenant data model and what it does not enforce
Permission engine for agent permissions, constraints and templates
Relationship-based access control for the resource tree and custom rules
Policy engine for combining roles, relations and delegation in one call
SSO for SAML and OIDC details
SCIM for the provisioning endpoints
SCIM filter reference and PATCH reference for IdP compatibility work
Admin for manual user management
Audit log for tracing what agents did

FAQ

Should I use the tenant module or the organization module?

Use organizations for human members, roles and SSO connections. The tenant module is a record that agents can reference, and the docs state it does not enforce isolation. Check agent.tenantId yourself if you use it.

Can one organization have more than one SSO connection?

The docs show listConnections(orgId), which returns all connections for an org, and each connection has its own domain. Whether you can attach two connections to the same domain is not documented, so test that case before you promise it to a customer.

Does SCIM deprovisioning log users out?

No. It sets a banned flag and a scim:deprovisioned marker. The sign-in modules do not read that flag, so you must check it in your own session code, including on refresh.

Do I need SAML if I already support OIDC?

Often yes. Plenty of enterprise customers run Okta or Azure AD in SAML mode and will not switch for you. The sso config accepts both lists, and each connection has a type of saml or oidc.

Where do custom permission strings live?

Custom roles store plain strings such as invoices:read on the organization. You check them with hasPermission. The policy engine splits role permissions on the last colon, so keep that format if you plan to use it.

Is ReBAC required for a B2B app?

No. Roles cover a lot of products. Add ReBAC when you need per-resource sharing, such as documents or projects shared with a subset of an org.

Which part of your own B2B auth took the longest to get right, and would you automate it differently now?

Try it yourself

Next: guide 4, migrating from Auth0 or Clerk. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

Enterprise auth lives in the glue between modules, so read the gaps before you promise a customer anything.

theAuth for AI Agents: Identity and Scoped Permissions

GDS K S — Sat, 10 Oct 2026 21:53:41 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

Last spring I found one API key in four places. It sat in a cron job, a Slack bot, a code-review agent, and a notebook a teammate had forgotten about. The key belonged to a human. It could read everything that human could read, and it could write most of it too.

Nothing was wrong yet. Then I asked a simple question: which of the four did that delete last Tuesday? I could not answer it. The logs said the human did it.

That is the problem this guide fixes. You will give each AI agent its own identity, its own token, and a short list of things it may do. By the end you will have a runnable script that creates agents, denies the wrong calls, logs every decision, and revokes one agent without touching the others.

I use theAuth for this, an open-source TypeScript library (@glinr/theauth). I wrote parts of it, so weigh my opinions accordingly. I will say plainly where it does not fit.

This is guide 5 of 8 in the theAuth guides. It stands on its own, so you can start right here. Nothing comes before it. It is the base for guides 6 to 8.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity (this guide)	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Step	What you do	Result
1	Install and create an instance	A local SQLite database with agents enabled
2	Seed an owner	One human row that agents hang off
3	Create one agent per job	A `kv_` token per agent, shown once
4	Call `authorize()` before every action	An allow or deny with an audit ID
5	Add constraints	Rate limits, argument patterns, time windows
6	Check tokens in middleware	401 and 403 at your HTTP edge
7	Delegate to sub-agents	A narrower scope, with an expiry
8	Read the audit trail, rotate, revoke	Answers to "which agent did that"

Prerequisites

You need Node 20 or newer, TypeScript, and a package manager. You do not need a running server or an external database. The examples use SQLite on disk so you can open the file afterward.

You also need one honest assumption: the agents in your system call tools you control. theAuth gives you the decision point. Your code must ask it before acting. If an agent can reach a database directly with its own credentials, no permission list in the world will stop it.

Why a shared key fails

A shared human key has three problems, and they stack.

First, the blast radius equals the human's permissions. A code reviewer that only needs to read pull requests inherits write access to everything.

Second, you cannot revoke one agent. Rotate the key and all four processes break at once. You wait, and the exposed key stays live.

Third, the audit trail lies. Every row names the human. Your compliance questions, and your own debugging, hit a wall.

A per-agent identity fixes all three. Each agent holds a token that maps to one row, one owner, and one permission list. The core concepts page describes the loop in one sentence: a user creates agents, agents call authorize() before acting, and every decision lands in the audit trail.

One distinction matters early. An agent is not a user. It has no email, no password, no session, and no OAuth account. It has a bearer token and a permission set. If you catch yourself wiring password reset for an agent, you want a user. The agent identity page draws that line.

Step 1: Install and create an instance

mkdir agent-identity-demo && cd agent-identity-demo
npm init -y
npm install @glinr/theauth
npm install -D tsx typescript

Now create demo.ts. I will build it up one piece at a time, and the full file is the sum of the blocks below.

import { createTheAuth } from '@glinr/theauth';

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  agents: {
    enabled: true,
    maxPerUser: 10,
    auditAll: true,
    tokenExpiry: '24h',
  },
});

Two settings deserve a note. auditAll records every authorize() call, and it defaults to on. tokenExpiry sets how long a new agent lives when you do not pass expiresAt. A 24 hour default means an agent you forget about stops working by tomorrow. I like that default. A forgotten credential should expire, not linger.

The quickstart walks through the same setup if you want the scaffolded Next.js version instead: https://docs.theauth.dev/quickstart.

Step 2: Seed an owner

Every agent has an owner, and the owner must exist as a row in theauth_users. That column is a foreign key. Skip this step and you will see FOREIGN KEY constraint failed on your first create call. Everyone hits it once.

If you already run theAuth's own auth modules, sign-up creates the row for you. In a scratch script, insert one:

import { users } from '@glinr/theauth';

theauth.db.insert(users).values({
  id: 'user-1',
  email: 'owner@example.com',
  name: 'Owner',
  createdAt: new Date(),
  updatedAt: new Date(),
}).run();

This insert pattern comes from the quickstart troubleshooting section and works for SQLite. For Postgres, the database docs list the matching call.

Step 3: Create one agent per job

Here is the rule I follow: one agent per job, not one agent per person. A nightly pull-request reviewer and a refund bot should never share an identity, even if the same human set up both.

const reviewer = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'pr-reviewer',
  type: 'autonomous',
  permissions: [
    { resource: 'mcp:github:*', actions: ['read'] },
  ],
  expiresAt: new Date(Date.now() + 7 * 24 * 3_600_000),
  metadata: { purpose: 'nightly PR review' },
});

const refunder = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'refund-bot',
  type: 'autonomous',
  permissions: [
    { resource: 'billing:refunds', actions: ['read', 'write'] },
  ],
});

console.log(reviewer.token); // kv_..., shown once

The token starts with kv_, followed by 32 random bytes in base64url, 46 characters in total. theAuth stores only the SHA-256 hash. A full database dump cannot reveal a live token.

That has a cost. You see the plaintext exactly once, at creation. Put it in your secrets manager before the process exits, or rotate to get a new one. You cannot recover it later.

Pick the right agent type

The type field takes three values.

An autonomous agent runs on its own, with no approval step unless a permission constraint demands one. Cron jobs and unattended assistants fit here. This is the default choice.

A delegated agent receives its permissions from another agent through a delegation chain. Use it for short-lived workers spun up for one task.

A service agent is a long-lived identity for infrastructure, such as an MCP server or an internal microservice. Treat it like a service account.

Mind the per-user cap

By default one user can own 10 active agents. The eleventh create call throws a plain Error with the message User <id> has reached the maximum of <n> active agents. The error has no dedicated code, and the REST endpoint reports it as a 500. Raise maxPerUser at initialization if you run a fleet, and catch the error by message, not by code.

Step 4: Check before every action

An agent identity does nothing until your code asks the question. Put one call in front of every sensitive operation.

const allowed = await theauth.authorize(reviewer.id, {
  action: 'read',
  resource: 'mcp:github:repos',
});
console.log(allowed.allowed); // true

const denied = await theauth.authorize(reviewer.id, {
  action: 'write',
  resource: 'mcp:github:repos',
});
console.log(denied.allowed, denied.reason); // false, plus a reason
console.log(denied.auditId); // links to the audit row

The result is { allowed, reason?, auditId }. The reviewer holds only read. A write on the same resource fails, and the denial lands in the audit log with its reason.

How resource patterns match

Resources are colon-separated strings. You pick the convention. mcp:github:repos, billing:refunds, and db:users:write all work. Consistency matters more than syntax.

The wildcard has one behavior that surprises people. A * segment is not a single-segment wildcard. The matcher stops at the first * and accepts everything after it, including nothing. That means mcp:github:* matches mcp:github:repos, mcp:github:repos:comments, and mcp:github itself.

Put * only in the last position. A pattern like mcp:*:repos looks like "any server, repos only," but it accepts mcp:slack:channels too. Without a wildcard, the pattern and resource must have the same number of segments. The full table lives on the permissions page.

Actions are free-form

The action list has no fixed set. read, write, execute, and delete are common, but you can define comment or refund if that reads better in your logs. theAuth checks that the requested action appears in the permission's actions array. It does not interpret the word.

Step 5: Add constraints

A permission can carry constraints, and every one must pass. This is where least privilege gets specific. "May write files" becomes "may write files under /tmp/agent/, 20 times an hour, from the office network."

const filer = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'file-writer',
  type: 'autonomous',
  permissions: [
    {
      resource: 'tool:file_write',
      actions: ['execute'],
      constraints: {
        maxCallsPerHour: 20,
        allowedArgPatterns: ['^/(home/agent|tmp)/'],
        timeWindow: { start: '09:00', end: '17:00' },
        ipAllowlist: ['10.0.0.0/8'],
      },
    },
  ],
});

const outside = await theauth.authorize(filer.id, {
  action: 'execute',
  resource: 'tool:file_write',
  arguments: { path: '/etc/passwd' },
  ip: '10.1.2.3',
});
console.log(outside.allowed); // false, the path fails the pattern

Each constraint has edges you should know before you rely on it.

Rate limits

maxCallsPerHour counts calls per agent and resource over a rolling hour, in 5-minute buckets. Calls beyond the limit get a reason that starts with Rate limit exceeded. The audit log records them as denied, not rate_limited, even though the type allows both values.

Argument patterns

allowedArgPatterns takes regular expression strings. Every string value in arguments must match every pattern. If you list two alternatives as two patterns, nothing will ever pass. Write one pattern with an alternation instead. The check skips non-string values, and it skips the whole request when arguments is missing.

That last detail matters. If your tool wrapper forgets to pass arguments, the constraint silently does nothing. Pass them every time.

Time windows

The timeWindow compares HH:MM strings against the server's local clock, not UTC. Windows that wrap past midnight, such as 22:00 to 06:00, are not supported. If you need a night shift, you will need to model it differently or enforce it outside theAuth.

IP allowlists

ipAllowlist takes exact IPv4 addresses and IPv4 CIDR ranges. IPv6 is not supported. You must pass ip on the authorization request. A request with no ip fails, which is the safe default.

Approval gates

Set requireApproval: true and authorize() always denies with the reason This action requires human approval before execution.

const deployer = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'deploy-bot',
  type: 'autonomous',
  permissions: [
    { resource: 'mcp:deploy:staging', actions: ['execute'] },
    {
      resource: 'mcp:deploy:production',
      actions: ['execute'],
      constraints: { requireApproval: true },
    },
  ],
});

Read the approval docs carefully, because this one trips people up. theAuth does not ship an approval UI, and authorize() never looks up approvals. After a human approves, authorize() still denies. Your application performs the action itself once theauth.approval.get(id) says approved. The enforcement point is theAuth. The workflow is yours. The approval flows page has the request, approve, and cleanup calls.

Step 6: Start from templates when you can

Writing permission arrays by hand gets old. theAuth ships named templates as plain Permission[] arrays.

import { permissionTemplates, getPermissionTemplate } from '@glinr/theauth';

const reader = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'docs-reader',
  type: 'autonomous',
  permissions: [
    ...permissionTemplates.mcpBasic,
    { resource: 'tool:custom_tool', actions: ['execute'] },
  ],
});

const copy = getPermissionTemplate('mcpBasic'); // deep copy, safe to edit

The names are readonly, readwrite, admin, mcpBasic, mcpFull, rateLimitedRead, approvalRequired, and businessHours. Do not reach for admin out of habit. It grants every action on every resource, which is the shared human key all over again.

One gotcha. Spreading from permissionTemplates copies references to the shared objects. If you mutate an entry afterward, you change the template for everyone. Use getPermissionTemplate whenever you plan to edit.

Step 7: Check tokens at your HTTP edge

Until now, the agent's ID went straight into authorize(). In a real system the agent calls your API with a bearer token. Use authorizeByToken in middleware.

export async function handle(request: Request): Promise<Response> {
  const token = request.headers.get('Authorization')?.replace('Bearer ', '');
  if (!token) return new Response('Unauthorized', { status: 401 });

  const result = await theauth.authorizeByToken(token, {
    action: 'read',
    resource: 'mcp:github:repos',
  });

  if (!result.allowed) {
    return new Response(result.reason ?? 'Forbidden', { status: 403 });
  }

  return Response.json({ ok: true, auditId: result.auditId });
}

theAuth hashes the token, looks it up, evaluates the permissions, and logs the decision. No JWTs, and no network round trip to a separate auth service. The call hits your own database.

Two behaviors differ between the two entry points, and both bite in production.

The first is expiry. authorizeByToken rejects an expired agent and flips its status to expired. authorize(agentId) only checks status, so it does not notice an elapsed expiresAt until something marks the agent expired. If you call by ID in a background worker, add your own expiry check or route through the token path.

The second is delegation. authorizeByToken checks the agent's own permissions only. authorize(agentId, ...) applies permissions held through delegation. If your sub-agents rely on delegated scopes, call it by ID.

The quickstart also shows a Hono setup on Cloudflare Workers if you want a framework example.

Step 8: Delegate to sub-agents without widening scope

Orchestrators spawn workers. The worker should get less than the parent, never more.

const worker = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'issue-summarizer',
  type: 'delegated',
  permissions: [], // starts empty
});

await theauth.delegate({
  fromAgent: reviewer.id,
  toAgent: worker.id,
  permissions: [{ resource: 'mcp:github:issues', actions: ['read'] }],
  expiresAt: new Date(Date.now() + 3_600_000), // one hour
  maxDepth: 2,
});

const held = await theauth.delegation.getEffectivePermissions(worker.id);
console.log(held);

An agent cannot delegate permissions it does not hold. The attempt fails at delegation time, not at the next authorize(). Each link carries an expiry and a depth counter. Revoking a link cascades to every delegation made onward from it.

The delegation docs cover depth limits and revocation order. For one-off jobs that should vanish on their own, look at ephemeral sessions.

Step 9: Read the audit trail

Now the payoff. Remember the Tuesday delete I could not trace? Here is the query that answers it.

const denials = await theauth.audit.query({
  agentId: filer.id,
  result: 'denied',
  limit: 50,
});

for (const row of denials) {
  console.log(row.timestamp, row.action, row.resource, row.reason);
}

const csv = await theauth.audit.export({ format: 'csv' });

Each row holds the agent ID, the owner's user ID, the action, the resource, the arguments, the result, the reason, and the evaluation time in milliseconds. Filter by since, until, actions, userId, or result.

Some limits to plan around. Calls rejected before the permission engine runs, such as an unknown or revoked agent, are not logged. Exports cap at the 10,000 most recent entries, so page through audit.query for more. The actions filter applies after limit and offset, so a page can come back shorter than you asked for.

The SDK never edits entries, but tamper evidence is your database's job. The audit trail page is honest about this, and so should you be if an auditor asks. theAuth does not make you compliant by itself.

Step 10: Rotate and revoke

Two operations finish the lifecycle.

// New token, old one invalid immediately, no overlap window
const rotated = await theauth.agent.rotate(reviewer.id);
console.log(rotated.token);

// Permanent. You cannot undo it.
await theauth.agent.revoke(refunder.id);

Rotation is a single update, so no moment exists where both tokens work. Rotate on a schedule and whenever you suspect exposure. Only active agents can rotate.

Revocation is permanent. To restore access, create a new agent. I think that is the right call. A revoked credential that can come back is a credential an attacker can wait out.

Permission edits through theauth.agent.update take effect immediately for new requests. In-flight requests that already passed authorization are not affected.

Run the whole file and watch the cap, the denials, and the audit rows:

npx tsx demo.ts

When you need the policy engine

authorize() is a simple path. It stops at the first permission that matches the resource and action, then falls back to delegated permissions. It does not expand roles and does not walk relationship graphs.

When you need those, call theauth.policy.evaluate() directly.

const decision = await theauth.policy.evaluate({
  subject: { agentId: reviewer.id },
  action: 'read',
  resource: 'mcp:github:repos',
  context: { ip: '203.0.113.42' },
});

console.log(decision.allowed, decision.effect, decision.reason);
console.log(decision.cacheHit, decision.durationMs);

The engine considers every matching permission and combines the results with deny-overrides by default. One failing constraint wins over any number of permits. If nothing matches, the effect is indeterminate with the reason POLICY_NO_MATCHING_PERMISSION, and allowed is false. Treat indeterminate as a deny.

This difference has teeth. Imagine an agent with two permissions that both match mcp:deploy:prod: a broad one, and a narrow one with a time window. authorize() evaluates the first match. evaluate() evaluates both and denies outside the window. The two paths can disagree, and the docs say so directly.

Five limits apply to the engine today, and I would rather you hear them from me.

The decision cache is process-local, with 10,000 entries and a 60 second TTL by default. Nothing calls invalidate() for you when permissions change, so call theauth.policy.invalidate({ agentId }) after a mutation you need to take effect now. In a multi-instance deployment, other processes keep stale entries until the TTL runs out.

Constraints on delegated permissions are not applied inside evaluate(). Only resource and actions carry over. If a delegated scope relies on a time window, enforce it another way.

User-only subjects write no audit row, because audit_logs.agent_id is not nullable.

The engine also has no declarative policy language. Permissions are plain objects. If your security team demands Cedar or Rego, this is not the right fit today. The policy engine page lists every known gap, and the ReBAC page covers relationship checks.

Optional layers: trust and DIDs

Two features sit on top of identity. You can skip both.

Trust scores

Trust scoring computes a 0 to 100 value from the agent's audit log. A new agent starts at 50. Successful calls add up to 25 points, each denial costs 5, and age adds up to 15. The level maps to untrusted, limited, standard, trusted, or elevated.

const score = await theauth.trust.computeScore(reviewer.id);
console.log(score.score, score.level);

Scores compute on demand. No background scorer runs, and the core hardcodes the thresholds today. A brand-new agent sits at limited, which surprises people. Use the level to route sensitive actions to a human, and treat the number as a hint, not a verdict. Details are on the trust scoring page.

Portable DIDs

Bearer tokens work fine inside one deployment. When an agent must prove its identity across an organizational boundary, you can give it a W3C DID backed by an Ed25519 key.

const { agentDid, privateKeyJwk } = await theauth.did.generateKey(reviewer.id);
console.log(agentDid.did); // did:key:z6Mk...

const signed = await theauth.did.sign(
  reviewer.id,
  { action: 'review', repo: 'acme/api' },
  privateKeyJwk,
);

Know the scope before you build on it. theauth.did.verify() looks up the public key in the theAuth database, so it only verifies DIDs created by the same instance. A third party holding only a DID string cannot use it. The private key is also returned once and never stored. Treat it like a bearer token. The DID identity page spells out the lower-level verifyPayload route for outside verifiers.

Troubleshooting and gotchas

FOREIGN KEY constraint failed on create

You skipped Step 2. The owner must exist in theauth_users first.

Token works, then suddenly 403

Check expiresAt. The default expiry is 24 hours from creation. authorizeByToken flips the status to expired, and an expired agent stays expired. Create a new agent or set a longer expiresAt up front.

A permission seems to do nothing

authorize() evaluates only the first permission whose resource and action match. If its constraints fail, it never tries later matches. Two overlapping permissions on one resource are a trap, so merge them into one.

The argument constraint never fires

Your call omitted arguments. The check skips requests with no arguments. Also confirm the value is a string, because the check skips other types.

The time window blocks at the wrong hour

The window uses the server's local time. A container running in UTC will interpret 09:00 as 09:00 UTC. Pin the timezone or compute against it deliberately.

Approved, but still denied

Expected. authorize() does not consult approvals. Run the action from your own code after the approval status flips.

A permission change does not seem to apply

Look at the cache if you use evaluate(). The cache can serve decisions for up to the TTL, 60 seconds by default, and nothing invalidates them for you. Call invalidate right after the change.

Go deeper

The pages below cover what this guide skipped.

Agent identity: the full lifecycle and field reference
Permission engine: matching rules, constraints, templates
Policy engine: deny-overrides, caching, limits
Core concepts: the mental model in one page
Delegation chains: depth limits and cascading revocation
Approval flows: human-in-the-loop requests
Audit trail: queries, exports, compliance notes
Trust scoring: the formula and the five levels
DID identity: portable identity and signed payloads
ReBAC: relationship checks for the policy engine

FAQ

Why not just use one API key per agent from my provider?

You can, and it beats sharing. But a provider key gives you one scope level, set by the provider. It does not give you per-resource patterns, rate limits per tool, or one audit trail across vendors. Per-agent keys also do not know about your internal tools.

Does an agent need a user account?

No, but it needs an owner. Agents have no password, session, or OAuth flow. Each one belongs to a user row, and that user must exist before you create the agent.

What happens if the agent leaks its token?

Rotate it. The old token dies immediately, with no overlap. Because theAuth keeps only the SHA-256 hash, a database leak does not expose live tokens. A leaked plaintext token, from a log line for example, is still usable until you rotate or revoke.

Is this a replacement for OAuth?

No. Humans signing in still use sessions or OAuth. Agent tokens cover non-interactive callers. For MCP servers that real users connect to, theAuth also ships an OAuth 2.1 server, which is a separate path from agent tokens.

When should I not use this?

If you run one agent, with one scope, in one process, a scoped provider key and a log line may be enough. This library earns its place once you run 5 or more agents, 2 or more owners, or an auditor asking questions.

Can I run it without SQLite?

Yes. The quickstart shows a D1 binding for Cloudflare Workers, and the database docs list the other providers. Use SQLite for local work and a server database in production.

Your turn

Which of your agents holds the widest key right now, and what would break if you cut its permissions to one resource? I would like to hear the answer, especially if the answer is "I do not know."

Try it yourself

Next: guide 6, spend caps and human approval. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

Every agent that can act should be able to answer one question: who exactly was that?

Migrate from Auth0 or Clerk to theAuth, Step by Step

GDS K S — Sat, 10 Oct 2026 21:45:58 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

Every auth migration I have seen goes wrong in the same place. The code diff is easy. The users are hard.

You can swap a provider component in an afternoon. Then you find out that your 40,000 password hashes are bcrypt, the new system wants PBKDF2, and every signed-in user will land on a login page at 9 a.m. on a Monday. Nobody wrote that down in the plan.

This guide walks through moving an app from Auth0 or Clerk to theAuth, an open-source, self-hosted auth library for humans and AI agents (@glinr/theauth on npm). I will cover the inventory, the user export, mapping sessions and orgs, a cutover you can roll back, and a plain list of what does not migrate. A short note on Better Auth sits near the end.

I am going to be blunt about fit. For some teams, staying put is the right call. I will say which ones.

This is guide 4 of 8 in the theAuth guides. It stands on its own, so you can start right here. Read it any time you are coming from Auth0 or Clerk. Guide 1 shows the target setup.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk (this guide)	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Question	Short answer
Do passwords migrate?	No. Hashes are bcrypt, theAuth verifies PBKDF2 only. You force a reset or rehash on next sign-in
Do sessions migrate?	No. Users sign in once after cutover, unless you run both stacks side by side
Do OAuth tokens migrate?	No. Users re-authorize each provider on first sign-in
Do users and org structure migrate?	Yes, through SQL inserts into theAuth tables you run yourself
Is there a user import API?	No. You write directly to the tables
Is there a hosted login page?	No. You build the forms with hooks
Can I roll back?	Yes, if you keep the old provider alive through one full refresh cycle

Prerequisites

You need four things before you start.

A Postgres database (theAuth also supports SQLite, MySQL, and D1, but the examples here use Postgres)
A TypeScript app. The code here uses a Next.js App Router layout, but adapters exist for other frameworks
Admin access to your current provider so you can export users and edit OAuth app callback URLs
A staging environment. Do not rehearse this in production

If you have never touched theAuth, skim the quickstart first. It takes ten minutes and gives you a working instance to point your migration script at.

Should you migrate at all?

Let me save you a weekend. Here are the cases where I would tell you to wait.

If you rely on Auth0's Universal Login, Guardian push MFA, or its bot and breached-password protection at the edge, theAuth does not replace those. It ships headless building blocks, not a hosted page. TOTP and passkeys exist. Push MFA does not.

If you lean hard on Clerk's hosted <SignIn /> and <SignUp /> components and its organization admin console, you will be rebuilding those screens. The organization model ports cleanly. The UI does not come with it.

If you are on an enterprise plan with a support SLA, remember that an open-source library has no 24/7 hotline. You are the operator now.

The cases where moving makes sense look different. Your monthly active user bill has outgrown the value. You are adding AI agents and want delegation, per-agent rate caps, and an MCP OAuth 2.1 server in the same system. Or you want your own cookie domain, token issuer, and audit trail. The comparison page lays out the structural differences against Clerk and Auth0 if you want the long version.

If you are still reading and still interested, good. On to the work.

Step 1: Inventory what you actually use

Before you write any theAuth code, list every place your app touches the old provider. I do this with a plain text search and a spreadsheet. The goal is a table with three columns: feature, where it lives, and whether theAuth covers it.

Search your repo for the provider imports. For Clerk that means @clerk/nextjs, @clerk/backend, clerkMiddleware, and any app/api/webhooks/clerk route. For Auth0 it means @auth0/nextjs-auth0, handleAuth, and any Management API calls.

Then check the dashboard for the things that never show up in code. Auth0 Rules and Actions. Clerk JWT templates. Social connections and their callback URLs. Machine-to-machine clients. Enterprise connections. Email templates.

Here is the mapping I use, pulled from the official migration pages.

Old concept	theAuth counterpart
Auth0 tenant	One `createTheAuth` instance per deployment
Clerk `<ClerkProvider>`	`<TheAuthProvider>` from `@glinr/theauth-react`
Auth0 or Clerk social connection	A provider inside the `oauth` plugin
Auth0 M2M client	An agent with `type: 'service'`
Auth0 Action or Rule	Your own route handler, or `customClaims` on the JWT session module
Clerk JWT template	`createJwtSessionModule` with `customClaims`
Clerk or Auth0 Organizations	`org: {...}` config plus the `organization()` plugin
Clerk webhooks	Signed webhooks and event streaming from your own process
Tenant logs	`theauth.audit.query()` and the audit export

Two rows in that table need a closer look, because they are where surprises hide.

First, Auth0 Actions. theAuth has no sign-in or sign-up hook. The hooks option exists, but it covers agents only: beforeAuthorize, afterAuthorize, beforeAgentCreate, afterAgentCreate, onAgentRevoke, and onViolation. If an Action blocks sign-ins from certain domains, you now write that check in your own handler around theauth.username.signIn. See the lifecycle hooks page for the exact shapes.

Second, Clerk webhooks. They fire from Clerk's internal events. They will not fire from theAuth. If you sync users to Stripe or a CRM from those webhooks, you port that logic to a webhook consumer or a call inside your own sign-up handler. The webhooks docs and the event streaming docs cover what theAuth can send.

Finish the inventory by counting. Count your users, then split them into password users and social-only users. Count your M2M clients or service integrations, and your orgs. Those numbers decide your cutover shape.

Step 2: Stand up theAuth next to the old provider

Do not remove anything yet. Install the package and create an instance in a new file.

npm install @glinr/theauth @glinr/theauth-nextjs @glinr/theauth-react

// lib/theauth.ts
import { createTheAuth } from '@glinr/theauth';
import { organization } from '@glinr/theauth/auth';

let instance: Awaited<ReturnType<typeof createTheAuth>> | null = null;

export async function getTheAuth() {
  if (!instance) {
    instance = await createTheAuth({
      database: {
        provider: 'postgres',
        url: process.env.DATABASE_URL!,
      },
      secret: process.env.THEAUTH_SECRET!,
      baseUrl: process.env.AUTH_BASE_URL!,
      auth: { session: { secret: process.env.SESSION_SECRET! } },
      username: { password: { minLength: 8 } },
      org: {},
      plugins: [organization()],
    });
  }
  return instance;
}

Three things in that block matter.

The org: {} key is what makes theauth.org available for server-side calls. The organization() plugin on its own only adds the HTTP endpoints. People trip on this one, so I am saying it twice.

The password module is username-based. theAuth has no emailAndPassword switch. The username and password page explains the shape. In practice, you store the lowercased email as the username, and users keep signing in with their email address.

createTheAuth creates its own tables, all prefixed theauth_. Run it once against your database before you import anything. You do not create a users table yourself.

Mount the route handler

Clerk hides route handling inside middleware. theAuth gives you an explicit handler you can read.

// app/api/auth/[...theauth]/route.ts
import { theAuthNextjs } from '@glinr/theauth-nextjs';
import { getTheAuth } from '@/lib/theauth';

const theauth = await getTheAuth();

// basePath must match the folder this catch-all route lives in
export const { GET, POST, PATCH, DELETE, OPTIONS } = theAuthNextjs(theauth, {
  basePath: '/api/auth',
});

Note the comment. The default base path is /api/theauth. If your folder is /api/auth, pass it explicitly or your client calls will 404.

Step 3: Export users from the old provider

This is the step with the real risk. Take it slowly.

Exporting from Clerk

The Backend API does the work here. Pagination caps at 500 users per page, so you loop.

// scripts/export-clerk-users.ts
import { clerkClient } from '@clerk/backend';
import { writeFileSync } from 'node:fs';

const clerk = clerkClient({ secretKey: process.env.CLERK_SECRET_KEY! });

const out: unknown[] = [];
let offset = 0;
const limit = 500;

while (true) {
  const { data } = await clerk.users.getUserList({ limit, offset });
  if (!data.length) break;
  out.push(...data);
  offset += data.length;
  if (data.length < limit) break;
}

writeFileSync('./clerk-users.json', JSON.stringify(out, null, 2));
console.log(`exported ${out.length} users`);

Load that file into a staging table called clerk_user_import. Then insert into the theAuth tables. This version keeps Clerk's user id, so your foreign keys survive.

INSERT INTO theauth_users (
  id, email, name, email_verified, created_at, updated_at
)
SELECT
  id,
  lower(email_addresses->0->>'email_address'),
  NULLIF(trim(COALESCE(first_name, '') || ' ' || COALESCE(last_name, '')), ''),
  (email_addresses->0->'verification'->>'status') = 'verified',
  to_timestamp(created_at / 1000.0),
  to_timestamp(updated_at / 1000.0)
FROM clerk_user_import
ON CONFLICT (id) DO NOTHING;

Then the social links, one row per provider connection.

INSERT INTO theauth_oauth_accounts (
  id, user_id, provider, provider_account_id,
  access_token, refresh_token, created_at, updated_at
)
SELECT
  gen_random_uuid()::text,
  u.id,
  replace(e.value->>'provider', 'oauth_', ''),
  e.value->>'provider_user_id',
  '',
  NULL,
  to_timestamp(u.created_at / 1000.0),
  to_timestamp(u.updated_at / 1000.0)
FROM clerk_user_import u,
     jsonb_array_elements(u.external_accounts) e;

Two details. The empty string for access_token is deliberate: the column is NOT NULL and Clerk does not export live tokens. And theauth_users has no image column, so the import skips Clerk's image_url. If avatars matter, store them in the metadata column or a table of your own.

Exporting from Auth0

The Management API bulk export returns your users as JSON lines. Password hashes are the catch. Auth0 releases them through a support request, so open that ticket early. It can take days. Social-only users have no hash at all.

The import script below inserts users and, for password users, writes an unusable placeholder into theAuth plus the real bcrypt hash into a legacy_password_hashes table that you own.

// scripts/import-auth0.ts
import fs from 'node:fs';
import readline from 'node:readline';
import { randomUUID } from 'node:crypto';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const stream = readline.createInterface({
  input: fs.createReadStream('auth0-users.ndjson'),
});

for await (const line of stream) {
  const u = JSON.parse(line);
  const email = String(u.email).toLowerCase();

  const inserted = await pool.query(
    `INSERT INTO theauth_users
       (id, email, name, email_verified, metadata, force_password_reset, created_at, updated_at)
     VALUES ($1, $2, $3, $4, $5, $6, now(), now())
     ON CONFLICT (email) DO UPDATE SET updated_at = now()
     RETURNING id`,
    [randomUUID(), email, u.name ?? null, Boolean(u.email_verified),
     JSON.stringify(u.app_metadata ?? {}), Boolean(u.passwordHash)],
  );
  const userId: string = inserted.rows[0].id;

  if (u.passwordHash) {
    await pool.query(
      `INSERT INTO theauth_username_accounts
         (id, user_id, username, password_hash, created_at, updated_at)
       VALUES ($1, $2, $3, 'imported:unusable', now(), now())
       ON CONFLICT DO NOTHING`,
      [randomUUID(), userId, email],
    );
    await pool.query(
      `INSERT INTO legacy_password_hashes (user_id, username, bcrypt_hash)
       VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`,
      [userId, email, u.passwordHash],
    );
  }
}

await pool.end();

Create legacy_password_hashes yourself before running this. That table belongs to you, not to theAuth. Also swap randomUUID() for Auth0's id if your own foreign keys depend on it.

One more field to watch. The script sets force_password_reset to true for anyone with a hash, so nobody can sign in with the placeholder. You lift that flag later, either through a reset or a rehash.

Check the counts

After either import, compare numbers. Rows in theauth_users should equal your exported user count, minus any duplicate emails. If they do not match, stop and find out why. A 2 percent gap you ignore today becomes 2 percent of your support queue next week.

Step 4: Decide how password users get back in

Neither provider's hashes verify in theAuth. The username module accepts PBKDF2 only, in the format pbkdf2:<iterations>:<saltHex>:<hashHex> using SHA-256. A bcrypt hash in password_hash is simply rejected at sign-in.

theAuth also ships no import API and no legacy-hash option. The Clerk page says it directly: options like verifyLegacyHash do not exist, and calling theauth.username.signUp for an imported user would create a duplicate account. That leaves two honest choices.

Option A: forced reset

Simplest and safest. Configure the passwordReset module on createTheAuth (it needs resetUrl and sendResetEmail), then send each user through POST /auth/forgot-password. The placeholder row is what lets the reset flow find them. A successful reset clears force_password_reset.

The cost is friction. Every password user gets an email and has to act. Expect a drop in active users from people who never open it. The reset module revokes existing sessions on success by default, which is what you want here. The email and password page lists the supporting modules, including reset and email verification.

Option B: lazy rehash

Verify the bcrypt hash yourself the next time the user types their password, write a PBKDF2 hash in theAuth's format, then call theauth.username.signIn.

import { compare as bcryptCompare } from 'bcrypt';
import { pbkdf2Sync, randomBytes } from 'node:crypto';
import { Pool } from 'pg';
import { getTheAuth } from '@/lib/theauth';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

function pbkdf2Format(password: string): string {
  const iterations = 600_000;
  const salt = randomBytes(16);
  const hash = pbkdf2Sync(password, salt, iterations, 32, 'sha256');
  return `pbkdf2:${iterations}:${salt.toString('hex')}:${hash.toString('hex')}`;
}

export async function signInWithLegacyBridge(username: string, password: string) {
  const theauth = await getTheAuth();
  const { rows } = await pool.query(
    'SELECT user_id, bcrypt_hash FROM legacy_password_hashes WHERE username = $1',
    [username.toLowerCase()],
  );
  const legacy = rows[0];

  if (legacy && (await bcryptCompare(password, legacy.bcrypt_hash))) {
    await pool.query(
      'UPDATE theauth_username_accounts SET password_hash = $1, updated_at = now() WHERE user_id = $2',
      [pbkdf2Format(password), legacy.user_id],
    );
    await pool.query(
      'UPDATE theauth_users SET force_password_reset = FALSE, updated_at = now() WHERE id = $1',
      [legacy.user_id],
    );
    await pool.query('DELETE FROM legacy_password_hashes WHERE user_id = $1', [legacy.user_id]);
  }

  return theauth.username?.signIn({ username, password });
}

Read that function twice. It runs in front of theAuth, in your code. You own the bcrypt check, you own the rehash, and you own the bugs. That is real security-sensitive code, so get a second pair of eyes on it and test the failure paths. A wrong password must fall through to signIn, which will reject it.

After 30 to 60 days, drop legacy_password_hashes and force a reset for anyone who never came back.

I would pick Option B for a consumer app where friction costs sign-ups, and Option A for a B2B tool where a reset email is routine. Mix them if you like. Run the lazy bridge for 45 days, then force the rest.

Step 5: Map sessions

Existing logins do not migrate. Full stop.

For Clerk, the __session cookie carries Clerk's signature, and theAuth cannot read it without calling Clerk. For Auth0, the same holds for its session cookies. A theAuth session row holds only an id, a user id, an expiry, and metadata, and the cookie is a signed token pointing at that row.

That leaves two paths.

Hard cutover

Every signed-in user signs in once on the new flow. Put a banner up three days ahead. This is the simplest option and I recommend it for most apps. A single forced sign-in is a minor annoyance, and it removes a whole category of "which system am I on" bugs.

Side by side with a rollout flag

Run both stacks. Each user sticks to one stack until you move them. A percentage-based middleware routes traffic.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  const userHint = req.cookies.get('migration_cohort')?.value ?? '';
  const onTheAuth =
    userHint === 'theauth' ||
    hashBucket(userHint) < Number(process.env.THEAUTH_ROLLOUT ?? '0');

  if (onTheAuth) return NextResponse.next();

  const url = new URL(req.nextUrl.pathname + req.nextUrl.search, process.env.LEGACY_ORIGIN!);
  return NextResponse.redirect(url);
}

function hashBucket(s: string): number {
  let h = 0;
  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0;
  return h % 100;
}

Start at THEAUTH_ROLLOUT=10. Watch error rates and sign-in conversion. Raise it over a week or two. Keep the legacy app on its own subdomain so the redirect has somewhere to land.

Replace the middleware check

If you used clerkMiddleware, there is no drop-in replacement. Next.js middleware runs on the Edge runtime by default, where you cannot open a Postgres connection to check a session. Keep middleware cheap and verify the cookie in server code.

// middleware.ts, cookie presence only
import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  if (req.cookies.get('theauth_session')) return NextResponse.next();

  const signInUrl = new URL('/sign-in', req.url);
  signInUrl.searchParams.set('next', req.nextUrl.pathname);
  return NextResponse.redirect(signInUrl);
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/private/:path*'],
};

A cookie that exists is not a cookie that is valid. The middleware check only filters out visitors with no cookie at all. The real check belongs where you can reach the database.

// lib/require-user.ts
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';
import { getTheAuth } from '@/lib/theauth';

export async function requireUser() {
  const theauth = await getTheAuth();
  const token = (await cookies()).get('theauth_session')?.value;
  const session = token ? await theauth.auth.session?.validate(token) : null;
  if (!session) redirect('/sign-in');
  return session;
}

session.validate(token) returns a Session or null. It does not throw. The username methods signIn and signUp do throw on failure, so wrap those in try and catch.

If you used Auth0 or Clerk custom claims in tokens, the replacement is the customClaims option on createJwtSessionModule. It receives { id, email, name } and returns extra claims. The JWT sessions page covers the secret length rule (32 characters or more) and refresh token rotation.

Step 6: Move organizations

This part is the pleasant surprise. The organization, membership, and role model ports cleanly. Built-in roles are owner, admin, member, and viewer.

const theauth = await getTheAuth();
const org = await theauth.org?.create({
  name: 'Acme',
  slug: 'acme',
  ownerId: userId,
});
if (org) {
  await theauth.org?.addMember(org.id, otherUserId, 'member');
}

Notice the optional chaining. theauth.org is null unless you passed org: {...} to createTheAuth.

For Clerk users, one cleanup task. Clerk roles carry an org: prefix, as in org:admin. In theAuth they are plain strings. Search your code for org: and strip the prefix anywhere you read orgMembership.role.

What does not come along is the admin UI. Clerk has a hosted org switcher and management console. You build your own against the organization plugin. The organizations page shows the endpoints, and the SaaS template from the scaffolder has a minimal org page you can copy.

Step 7: Move providers and rebuild the sign-in page

Social login moves from the dashboard into code.

import { createTheAuth } from '@glinr/theauth';
import { oauth, createGithubProvider, createGoogleProvider } from '@glinr/theauth/auth';

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.THEAUTH_SECRET!,
  baseUrl: process.env.AUTH_BASE_URL!, // must end with the adapter mount path, such as /api/auth
  auth: { session: { secret: process.env.SESSION_SECRET! } },
  plugins: [
    oauth({
      providers: {
        github: createGithubProvider({
          clientId: process.env.GITHUB_CLIENT_ID!,
          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        }),
        google: createGoogleProvider({
          clientId: process.env.GOOGLE_CLIENT_ID!,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        }),
      },
    }),
  ],
});

Two gotchas live here. The baseUrl must include the adapter mount path, because theAuth builds the redirect URI from it. And the callback URL pattern is {baseUrl}/auth/oauth/callback/<provider>. With the config above and a mount at /api/auth, that is <your-domain>/api/auth/auth/oauth/callback/github. Yes, auth appears twice. Change each OAuth app's callback URL in the provider console before cutover, or the first social sign-in fails. The OAuth page lists the supported providers and the generic OIDC factory for anything else.

The sign-in page

Clerk's <SignIn /> renders a hosted flow inside your layout. theAuth gives you hooks and expects a form.

The docs hide a trap worth quoting in spirit. The useSignIn hook posts { email, password } to ${basePath}/auth/sign-in. The TypeScript core and adapters do not register that route. The username module serves /auth/username/sign-in and /auth/username/sign-up with { username, password }, and you wire theauth.username.handleRequest(request) into a route handler yourself. Until you do, build the form against the username endpoints, or call theauth.username.signIn in a server action.

I mention it because I would rather you read it here than discover it at 11 p.m. with a 404 in the network tab.

Passkeys and phone OTP are server modules with their own endpoints. If your Clerk app showed first-party passkey or OTP screens, you rebuild those.

Step 8: Port machine-to-machine clients

This only applies if you are coming from Auth0 and run M2M clients. An M2M client becomes an agent with type: 'service'.

const agent = await theauth.agent.create({
  ownerId: opsUser.id,
  name: 'billing-pipeline',
  type: 'service',
  permissions: [
    {
      resource: 'mcp:stripe:*',
      actions: ['read'],
      constraints: { maxCallsPerHour: 1000 },
    },
    {
      resource: 'mcp:stripe:refund',
      actions: ['execute'],
      constraints: { requireApproval: true },
    },
  ],
});

The token comes back once, as a kv_-prefixed bearer, and theAuth stores only its SHA-256 hash. Hand it to the service immediately. Rotate with theauth.agent.rotate(agent.id). Revoke with theauth.agent.revoke(agent.id).

Two properties differ from Auth0. Rotation is atomic, so the old token dies the moment you issue the new one, with no overlap window. If a consumer cannot swap tokens instantly, plan the rotation around that. And rate caps, approval gates, time windows, and IP allowlists are constraints on the permission itself.

M2M clients should cut over last. Confirm the caps and approval gates in staging first. The agents page covers identity, delegation, and trust scoring in depth, and the audit page shows how to read the decisions back.

Step 9: The cutover plan

Here is the sequence I would run. It assumes a side-by-side rollout. Collapse steps if you take the hard cutover.

Stand up theAuth in staging against a copy of production data. Do a full import. Compare counts
Run a test sign-in for a sample of 20 to 50 users across each type: password, social-only, org admin, and one agent
Update OAuth app callback URLs so both the old and new URLs are valid where the provider allows it
Deploy theAuth to production behind a flag at 0 percent. Nothing changes for users
Move internal staff first. Then 10 percent of traffic. Watch the audit log for authorization failures and fix mismatches
Widen to 50, then 100 percent over one to two weeks
Cut M2M clients last, one service at a time
Leave the old provider running through one full session-refresh cycle (the migration docs suggest at least 7 days)
After the grace period, decommission the old tenant and drop legacy_password_hashes once the bridge window ends

Take a database snapshot before step 1 and again before step 6. Imports are idempotent in the scripts above because of ON CONFLICT, but a snapshot is cheaper than being clever.

Rollback

Rolling back is a routing change, not a data change, as long as you keep the old provider alive.

Flip the reverse proxy or middleware back to the old provider. Set THEAUTH_ROLLOUT=0
Users still holding old-provider cookies stay signed in. New sessions come from the old provider again
theAuth sessions stay valid locally until they expire, so nothing breaks for people already on the new stack

What rollback cannot undo is anything users did on theAuth alone. A password reset completed on the new system does not flow back to Auth0 or Clerk. A user who signed up after cutover does not exist in the old tenant. Keep the rollout window short, and write down the timestamp of your first production sign-up on theAuth. That is your point of no easy return.

What does not migrate

I will put the whole list in one place, since this is the part migration guides tend to bury.

Passwords do not migrate. You reset or rehash.

Sessions do not migrate. Users sign in again.

OAuth access and refresh tokens do not migrate. If your app calls GitHub or Google APIs using stored tokens, those calls fail until each user signs in once more. Plan a grace period and a graceful error.

Webhooks do not migrate. Clerk events stop when you stop using Clerk.

Hosted UI does not migrate. Login pages, org switchers, and admin consoles are yours to build.

Auth0 Rules and Actions do not migrate. They become code in your own handlers.

Avatars from Clerk have no dedicated column to land in, so they do not come along.

MFA enrollments are worth a mention. TOTP secrets and passkeys are not part of the export flows above, so assume users re-enroll. The two-factor page under Auth covers the new setup.

Troubleshooting and gotchas

Users report "invalid credentials" right after import

Check that the username in theauth_username_accounts is the lowercased email. Sign-in looks up the username, lowercased by default, and does not apply the sign-up pattern check. A mixed-case username will miss.

Reset emails never arrive

The passwordReset module needs both resetUrl and sendResetEmail. If you configured neither, the forgot-password route has nothing to send with. Test with one account before you mail 10,000 people.

Social sign-in returns a redirect URI mismatch

Re-read the callback URL pattern. Count the path segments. The auth segment appears twice when your adapter mounts at /api/auth. Provider consoles compare strings exactly.

The OAuth plugin throws on startup

It requires auth: { session: { secret } }. Set that secret even if you only use the plugin for social login.

`theauth.org` is null

You passed the organization() plugin but not org: {}. Add the config key.

Imported OAuth users get a fresh account

If the provider_account_id you imported does not match what the provider returns, theAuth treats the sign-in as a new identity. For Auth0 ids like google-oauth2|1234, the part after the pipe is the provider account id. For Clerk, strip the oauth_ prefix from the provider name.

A user signs in on the new stack but has no org data

Memberships need their own import. The user insert does not carry them. Script the org and membership copy and run it in the same window as the user import.

A note on Better Auth

If you are moving from Better Auth rather than a hosted service, the picture is friendlier. You own the database already, so the export step is a SQL copy, not an API crawl. The migration page has INSERT ... SELECT statements for the user and account tables. Skip the rows where providerId is credential.

Two things still do not carry over. Session tokens use a different structure, and credential hashes are not in PBKDF2 format, so the same reset or rehash choice applies. You can bridge sessions during the overlap by wrapping your old Better Auth session check in customAuth and passing it as auth.adapter, so both cookies resolve while traffic drains. One caveat from the docs: theauth.auth.resolveUser(request) consults only the adapter, so check theauth.auth.session too in your own server code if you need to accept both.

Better Auth is a good library. If you only need human auth and your provider list fits, you may not need to move at all. The full Better Auth guide covers the cookie defaults and the agent-auth package differences.

Go deeper

The three migration pages carry their own diffs and data scripts:

Concepts you will touch while migrating:

FAQ

Will my users have to sign in again on cutover day?

Yes, unless you run a side-by-side rollout. theAuth cannot verify Clerk or Auth0 session cookies. Tell users ahead of time and keep the old subdomain alive as a fallback.

Can I import users with their existing passwords?

Not directly. theAuth verifies PBKDF2 hashes only and has no user import API or legacy-hash option. You either force a password reset or write a bridge in your own sign-in handler that verifies bcrypt and rehashes on success.

Does theAuth replace Auth0 Actions or Clerk webhooks?

No. theAuth has no sign-in or sign-up hook, and Clerk's events do not carry over. The hooks option covers agents. For human flows, you put the logic in your own handlers, or use customClaims for token enrichment.

How long should I keep the old provider running?

At least one full session-refresh cycle. The migration docs suggest 7 days as a default. In practice, keep it until traffic to the old stack is near zero and your bridge window has ended.

Is theAuth a good fit if I only need human login?

Possibly, but weigh it honestly. The strongest reasons to move are agents, MCP, and ownership of your data and cookies. If you want a hosted login page and an admin console without building them, a hosted provider may serve you better.

Can I certify compliance by moving to theAuth?

No. Self-hosting and the GDPR export tooling give you building blocks. They do not certify your deployment against any regulation.

What I would do first

If I were starting tomorrow, I would do one thing before any code. I would run the user count query, split it into password users and social-only users, and decide between reset and lazy rehash based on that split. Everything else follows from it.

What is the one piece of your current auth setup that you are most afraid to move, and why?

Try it yourself

Next: guide 5 if you also run AI agents. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

The code diff takes an afternoon, the users take a plan, so write the plan first.

theAuth Passwordless Login: Passkeys, Magic Links, OTP

GDS K S — Sat, 10 Oct 2026 21:42:43 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

Last month I deleted a password reset email template from a side project. It felt strange. That template had been the busiest piece of copy in the whole app, and I had never once looked at it on purpose.

The reset flow existed because passwords exist. Remove the password and a whole class of support tickets disappears with it. But "go passwordless" is not one decision. You face a menu of five or six, and each item fails differently.

This guide walks through that menu using theAuth, an open-source auth library for TypeScript (npm package @glinr/theauth). You will wire up magic links, email OTP, passkeys and TOTP two-factor, add a breached-password check for the apps that still need passwords, and finish with a decision table you can screenshot. I stick to what the docs and package source actually ship. Where theAuth leaves a job to you, I say so.

This is guide 2 of 8 in the theAuth guides. It stands on its own, so you can start right here. It assumes a working login like the one in guide 1, but the passkey and OTP code reads fine on its own.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP (this guide)	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Method	Best for	What the user does	Main catch
Magic link	Low-frequency apps, B2B invites	Clicks a link in email	Single use, expires in 15 minutes by default
Email OTP	Mobile, or when links get mangled	Types a 6-digit code	Attempt limits, email delivery speed
Passkey	Daily-use apps, phishing resistance	Touch ID, Face ID, security key	Needs a signed-in user to register
TOTP 2FA	Adding a second factor to anything	Types an authenticator code	You wire it into sign-in yourself
Breach check	Apps that keep passwords	Nothing, it runs at sign-up	Fails open by default

If you only have ten minutes, ship magic links first, add a passkey enrollment prompt after the first sign-in, and put TOTP behind a setting for users who want it.

Prerequisites

You need Node 20 or newer, a Postgres database, and an email provider. My examples use Resend, but any provider works because theAuth hands you the address and the code or link and you do the sending.

You also need a session secret of at least 32 characters. Every email-based method below refuses to start without auth.session configured, because each one issues a session when verification succeeds.

pnpm add @glinr/theauth @glinr/theauth-nextjs @simplewebauthn/browser
openssl rand -base64 48   # use the output as SESSION_SECRET

I mount everything in Next.js App Router, but the same plugin config works with the Express, Hono, Fastify and other adapters listed on the adapters overview. If you want a scaffolded app instead, the quickstart has a pnpm create @glinr/theauth-app command that sets up a Next.js SaaS template.

How to choose before you code

Each method answers a different question, so pick by the question.

Magic links answer "can this person read this inbox right now?" Email OTP answers the same thing, but with a code the user types instead of a link they click. Passkeys answer "is this person holding a device I enrolled before?" TOTP answers "does this person also hold an authenticator app?"

The first two prove inbox control. That is only as strong as the user's email account. The passkey proves device possession plus a local biometric or PIN, and the browser ties it to your domain, so a lookalike phishing site cannot reuse it. TOTP adds a second proof, but a user can still type a TOTP code into a fake site, so TOTP does not resist phishing.

My default stack for a new app is this. Magic link or OTP as the front door. Passkey as the upgrade offered after first sign-in. TOTP for accounts that hold money or admin power. A breach check only if you accept passwords at all.

Step 1: Create the instance and mount the routes

Start with the shared module. All the examples below add to this one file.

// lib/theauth.ts
import { createTheAuth } from '@glinr/theauth';

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.env.APP_URL!,
  auth: { session: { secret: process.env.SESSION_SECRET! } },
  plugins: [],
});

Then add the catch-all route so the endpoints exist. The Next.js adapter page covers the full options.

// app/api/theauth/[...theauth]/route.ts
import { theAuthNextjs } from '@glinr/theauth-nextjs';
import { theauth } from '@/lib/theauth';

const handlers = theAuthNextjs(theauth);

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;

The default mount path is /api/theauth. Every fetch call below assumes it. If you mount elsewhere, pass basePath to the adapter and update the URLs.

Step 2: Magic links

Magic links are the cheapest passwordless method to ship. The magic link docs describe one plugin and one callback.

import { magicLink } from '@glinr/theauth/auth';

// inside createTheAuth({ plugins: [...] })
magicLink({
  appUrl: `${process.env.APP_URL}/api/theauth`,
  sendMagicLink: async (email, _token, url) => {
    await resend.emails.send({
      from: 'auth@example.com',
      to: email,
      subject: 'Your sign-in link',
      html: `<a href="${url}">Sign in</a>. This link expires in 15 minutes.`,
    });
  },
}),

Two details tripped me up on first read.

First, appUrl is not your marketing site. theAuth prepends it to the callback path, so it must point at wherever the verify endpoint is reachable. With the default mount, that is your public origin plus /api/theauth.

Second, the link lands on GET /auth/magic-link/verify?token=..., and that endpoint returns JSON. It does not set a cookie or redirect. Your app has to take session.token and store it, then send the user somewhere useful. In practice that means a small page of your own that calls the verify endpoint and handles the result.

Send and verify from the client

// request the link
await fetch('/api/theauth/auth/magic-link/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' }),
});
// 200 { sent: true }

// on your callback page, with ?token= in the URL
const res = await fetch(`/api/theauth/auth/magic-link/verify?token=${token}`);

if (res.status === 401) {
  // invalid, expired or already used: offer "send a new link"
}

const { user, session } = await res.json();
// user: { id, email }, session: { token, expiresAt }

What happens with unknown emails

A send for an unknown address creates a user record for it. That means the same form serves sign-in and sign-up, which users like. It also means anyone can create accounts for any address by typing it in. If that matters for you, put a CAPTCHA in front of the form. theAuth ships a captcha module for Turnstile, hCaptcha and reCAPTCHA. The module is not a plugin, so you call it from your own route handler before you send the link.

Rate limits

The send endpoint allows 5 requests per minute per IP, and extra requests get 429 with a Retry-After header. Show a visible countdown on the resend button. Users who click "resend" six times in a row are the ones who file tickets.

The tokenExpiry option defaults to 900 seconds. Email can arrive slowly, so I would not drop it below 600.

Step 3: Email OTP

OTP is the same idea with a different payload. Use it when the user is on a phone and the link would open the wrong browser, or when corporate email scanners pre-click links and burn single-use tokens. That second problem is real and nasty. A scanner that fetches the URL consumes the token before the human sees the email. A typed code avoids it.

The email OTP page covers the plugin.

import { emailOtp } from '@glinr/theauth/auth';

emailOtp({
  codeLength: 6,
  codeExpiry: 300,
  maxAttempts: 5,
  sendOtp: async (email, code) => {
    await resend.emails.send({
      from: 'auth@example.com',
      to: email,
      subject: `Your code: ${code}`,
      html: `<p>Your sign-in code is <strong>${code}</strong>. It expires in 5 minutes.</p>`,
    });
  },
}),

The three numeric options above are the documented defaults, so you can drop them. I wrote them out so you can see the knobs.

await fetch('/api/theauth/auth/email-otp/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email }),
});

const res = await fetch('/api/theauth/auth/email-otp/verify', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, code }),
});

const { user, session } = await res.json();

The behaviors worth knowing are these. Requesting a new code deletes the earlier one for that address. After maxAttempts wrong guesses the code dies and the user needs a fresh one. Verify allows 10 requests per minute per IP. A wrong, expired or exhausted code all return 401, so your UI cannot tell them apart and should not try.

Link or code, which one

I ship both on the same screen in some apps. The user types an email, and the message holds a link and a code. You can do this today by calling both plugins' send endpoints, but you would send two emails. If you want one email with both, you would need to generate that message yourself, and the docs do not describe a combined flow. I would pick one per app and move on.

Step 4: Passkeys

Passkeys are the method I want most users on, and the one with the most setup. The passkey docs lay out the plugin and the two ceremonies.

import { passkey } from '@glinr/theauth/auth';

passkey({
  rpName: 'My App',
  rpId: 'example.com',
  origin: process.env.APP_URL!,
}),

Get rpId and origin right or nothing works. The relying party ID must be a registrable domain suffix of the origin. For an app served from the app.example.com host, both app.example.com and example.com are valid. The server compares origin exactly against what the browser sends, so a missing www or a wrong port fails the check. For local work, set origin to the exact dev origin, port included.

The catch: registration needs a session

Registration needs an authenticated user. The docs state it plainly: the user must hold a session before registering a passkey. Passkeys are an upgrade path, not a first sign-up method. A new user arrives by magic link or OTP, and then you offer the passkey.

I like this shape anyway. The email step proves the address, the passkey makes every later visit one tap.

Register a passkey

import { startRegistration } from '@simplewebauthn/browser';

const optionsRes = await fetch('/api/theauth/auth/passkey/register/options', {
  method: 'POST',
  credentials: 'include',
});
const options = await optionsRes.json();

const credential = await startRegistration(options);

await fetch('/api/theauth/auth/passkey/register/verify', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ response: credential }),
});

The verify body wraps the browser credential in a response field. Miss that wrapper and you get a failure that looks like a bad credential.

Sign in with a passkey

import { startAuthentication } from '@simplewebauthn/browser';

const optionsRes = await fetch('/api/theauth/auth/passkey/authenticate/options', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
const options = await optionsRes.json();

const assertion = await startAuthentication(options);

const res = await fetch('/api/theauth/auth/passkey/authenticate/verify', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ response: assertion }),
});

const { user, session } = await res.json();

The options call takes an optional userId, not an email. Send an empty body and the browser offers any discoverable passkey for your domain. That is the setup you want for a "Sign in with a passkey" button that needs no username field.

With auth.session configured, verify returns the user and session and sets a theauth_session cookie. Without a session manager you get a raw { userId, credential } and no session. A failed assertion returns 401.

Tuning

The options table in the docs lists three knobs I touch. userVerification defaults to 'preferred', so set 'required' if you want a biometric or PIN check every time. attestation defaults to 'none', which is right for almost every consumer app. challengeTimeout defaults to 60000 milliseconds and caps at 300000.

Do not strand users

A user can list and delete their passkeys. If they delete the last one and have no other sign-in method, the app locks them out. Count credentials before you let the delete call through, or make sure email sign-in is still available. In my setup it always is, so a lost phone costs one magic link and nothing more.

const { credentials } = await (
  await fetch('/api/theauth/auth/passkey/credentials', { credentials: 'include' })
).json();

// each: { id, credentialId, deviceName?, createdAt, lastUsedAt, ... }

Step 5: TOTP two-factor

The two-factor docs describe a twoFactor() plugin with enrollment, verification and backup codes. Read the second paragraph of that page before you write any code, because it sets expectations.

theAuth stores and verifies the secret and backup codes. It does not sit inside your sign-in flow. No built-in "two factor required" challenge exists on the primary sign-in endpoints. You decide when to ask for a code.

That is a deliberate tradeoff, and you should know what you are signing up for. You get full control over where the prompt appears. You also own the gate, so a bug in your code is a bypass.

import { twoFactor } from '@glinr/theauth/auth';

twoFactor({ appName: 'My App' }),

Enroll

const res = await fetch('/api/theauth/auth/2fa/enroll', {
  method: 'POST',
  credentials: 'include',
});
const { secret, uri, backupCodes } = await res.json();

Render uri as a QR code with any QR library. Show backupCodes exactly once. theAuth keeps only hashes, so you cannot show them again later. Calling enroll a second time replaces the secret and the backup codes and turns 2FA off until the user confirms the new secret.

Enrollment is not done until the user proves the app works. Ask for a code and post it to the verify endpoint.

await fetch('/api/theauth/auth/2fa/verify', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: '482910' }),
});
// 200 { valid: true, activated: true }

Gate sign-in yourself

Here is the pattern the docs describe in prose, written out. Finish the primary sign-in on your server. Do not hand the session to the browser yet. Hold the user in a pending state, collect a code, verify it, and only then release the session.

The verify endpoint resolves the user from an Authorization: Bearer header, so your server can call it with the pending token. This sketch uses a pending map as a stand-in for your own store (a signed cookie, Redis, a table).

// server code, after the magic link or OTP verify succeeded
const pending = new Map<string, { token: string; expiresAt: string }>();

async function beginSecondFactor(session: { token: string; expiresAt: string }) {
  const ticket = crypto.randomUUID();
  pending.set(ticket, session);
  return ticket; // send this to the browser, not the session token
}

async function finishSecondFactor(ticket: string, code: string) {
  const session = pending.get(ticket);
  if (!session) return null;

  const res = await fetch(`${process.env.APP_URL}/api/theauth/auth/2fa/verify`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${session.token}`,
    },
    body: JSON.stringify({ code }),
  });

  const { valid } = await res.json();
  if (!valid) return null; // wrong code is a 200 with valid: false

  pending.delete(ticket);
  return session;
}

Check that valid field. A wrong code returns HTTP 200 with valid: false, so a status check alone lets everyone through. I would have shipped that bug if the docs had not called it out.

If you configure the top-level totp key instead of the plugin, theauth.totp.verify(userId, code) does the same check in-process and returns { valid, usedBackupCode? }. The docs say that module's own request handler takes a userId with no session check, so keep it off the public internet.

Backup codes

Enrollment makes ten backup codes of eight characters. The alphabet leaves out 0, O, 1 and I so people can read them off paper. A backup code works in place of a TOTP code at verify and disable, and each one works once. Regenerating via POST /auth/2fa/backup-codes kills the old set and requires a current code.

The verifier accepts codes one 30-second step either side of now, which tolerates modest clock drift on a phone.

Step 6: Skip the prompt on trusted devices

Asking for a code on every sign-in gets old, and users pick weaker habits to avoid it. The trusted device module lets you skip the prompt on a device the user already verified.

The module stands alone and does not wire itself into twoFactor. You call it in your own flow.

import { createTrustedDeviceModule } from '@glinr/theauth/auth';

const trustedDevice = createTrustedDeviceModule(
  {
    secret: process.env.TRUSTED_DEVICE_SECRET, // separate from the session secret
    trustDurationSeconds: 30 * 24 * 60 * 60,
    maxDevices: 10,
  },
  theauth.db,
);

After a successful second factor, mark the device. Before prompting on the next sign-in, check it.

// after the code is verified
const fingerprint = await trustedDevice.generateFingerprint(request);
await trustedDevice.trustDevice(user.id, fingerprint);

// on the next sign-in, before asking for a code
const fp = await trustedDevice.generateFingerprint(request);
if (await trustedDevice.isTrusted(user.id, fp)) {
  // skip the second factor and release the session
}

Three honest notes. If you leave out secret, theAuth uses a random per-process key, so every restart un-trusts every device. Set it. Rotating that secret later is also your kill switch, since it invalidates all trusted devices at once. And the fingerprint comes from four request headers (user-agent, accept-language, accept-encoding, accept), so a browser update changes it and the user sees one extra prompt. I treat it as a convenience feature and not as strong device identity.

You also get revokeDevice, revokeAllDevices and listDevices for a "your devices" settings page. Call revokeAllDevices on password change.

Step 7: Breached-password checks, if you keep passwords

Not every app can go fully passwordless. Enterprise customers ask for passwords. Legacy users have them. If you keep passwords, check them against known breaches.

The breach checking page covers createHibpModule, which calls the Pwned Passwords range API. It uses k-anonymity: only the first 5 characters of the SHA-1 hash leave your server. The API returns roughly 500 candidate suffixes and your server looks for a match locally.

import { createHibpModule, HibpBreachedError } from '@glinr/theauth/auth';

const hibp = createHibpModule({
  threshold: 0,
  timeoutMs: 5000,
  onError: 'allow',
});

async function handleSignUp(username: string, password: string) {
  try {
    await hibp.enforce(password);
  } catch (err) {
    if (err instanceof HibpBreachedError) {
      return { error: `That password appeared in ${err.count} known breaches. Pick another.` };
    }
    throw err;
  }
  return theauth.username?.signUp({ username, password });
}

The module is standalone. It does not hook into the username module on its own, so you call enforce() before signUp. Forget that and nothing gets checked.

Use check() when you want to warn without blocking. It returns the raw count and ignores threshold.

Fail open or fail closed

The default onError: 'allow' means a slow or unreachable API lets the password through. That keeps sign-up working during an outage. It also means an attacker who can block your egress to the API skips the check. For most apps I keep the default. If you run a regulated product, set 'block' and accept that enforce() will throw HibpApiError during outages.

Putting it together

Here is the final config with every piece in one place.

// lib/theauth.ts
import { createTheAuth } from '@glinr/theauth';
import { magicLink, passkey, twoFactor } from '@glinr/theauth/auth';

export const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.env.APP_URL!,
  auth: { session: { secret: process.env.SESSION_SECRET! } },
  plugins: [
    magicLink({
      appUrl: `${process.env.APP_URL}/api/theauth`,
      sendMagicLink: async (email, _token, url) => {
        await sendEmail(email, `Sign in: ${url}`);
      },
    }),
    passkey({
      rpName: 'My App',
      rpId: 'example.com',
      origin: process.env.APP_URL!,
    }),
    twoFactor({ appName: 'My App' }),
  ],
});

The user journey this gives you:

New visitor types an email and clicks the magic link.
Your callback page stores the session and shows a "Add a passkey" prompt.
Next visit, the passkey button signs them in with one tap.
Users with sensitive roles enroll TOTP, and your gate asks for a code on untrusted devices.

Rate limiting deserves a mention. The send and verify endpoints already carry their own per-IP caps. If you want per-route limits on the rest of /auth/*, the rate limiting page explains the opt-in rateLimit() plugin and notes that it limits nothing until you add it.

Troubleshooting and gotchas

Startup throws about auth.session

The magic link and email OTP plugins throw at startup without auth.session, and the secret must be at least 32 characters. Generate a longer one.

The magic link opens but nothing signs in

The verify endpoint returns JSON and sets no cookie. Your callback page must read session.token, store it, and redirect. If you point the email link directly at the API URL, the user sees raw JSON.

Passkey registration fails on localhost

Check origin first. It must match the exact origin in the address bar, including the port. Then check that rpId is a suffix of the host. Use the dev origin in config and keep it out of production builds.

Passkey sign-in returns 401

A 401 on authenticate verify means the assertion failed. Confirm you wrapped the assertion in { response: assertion }, and confirm the same rpId you run now produced the credential. Changing rpId later orphans every enrolled passkey.

Everyone passes the 2FA gate

You checked the status code. The verify endpoint returns 200 with valid: false on a wrong code. Read the field.

Trusted devices reset after deploys

You omitted secret. Set TRUSTED_DEVICE_SECRET to a stable value.

Users report "link expired" at random

Corporate mail scanners often fetch links before the human clicks. Single-use tokens die on that fetch. Switch those users to email OTP, or make your callback page require a button click before it calls verify.

Go deeper

Each of these pages goes further than I could here.

Passkey for the credential list, delete endpoint and full options table.
Magic link for tokenExpiry, callbackPath and the programmatic theauth.magicLink API.
Email OTP for code length, expiry and attempt limits.
Two-factor auth for disable, status and backup code regeneration.
Trusted devices for revocation and listing.
Password breach checking for self-hosted mirrors and fail-closed mode.
Sessions for cookie and JWT session handling after sign-in.
Email templates for the messages these flows send.
Authentication overview for every other sign-in method.

FAQ

Are passkeys better than passwords?

For most users, yes. The browser ties a passkey to your domain, so a phishing site cannot collect something reusable. It also removes password reuse and credential stuffing. The cost is recovery. You need a second way back in, such as email sign-in, for the day a user loses every device.

Should I use magic links or email OTP?

Choose links when users read mail on the same device they sign in on. Pick OTP when they cross devices, or when mail scanners eat your links. Both prove inbox control and nothing more, and both share the 5 sends per minute per IP cap on the send endpoint.

Does theAuth enforce two-factor on sign-in automatically?

No. It stores and verifies TOTP secrets and backup codes, and you decide where the challenge goes in your sign-in flow. That gives you control and puts the gate in your hands. The two-factor page says this directly.

Can a new user sign up with a passkey alone?

Not with the documented endpoints. Passkey registration requires an authenticated user. Have the user sign in once by magic link or OTP, then offer the passkey.

Is TOTP phishing resistant?

No. A user can type a TOTP code into a fake page, and the attacker can replay it within its 30-second window. TOTP stops stolen-password attacks. A passkey stops phishing. If phishing is your main risk, push users toward passkeys.

Do I still need a breach check if I go passwordless?

Only if you accept passwords anywhere. If every account uses links, codes and passkeys, there is no password to check.

What I would like to know

If you shipped passwordless login in production, which method did your users actually pick, and which one did you end up removing? I am especially curious whether anyone saw the mail scanner problem at scale.

Try it yourself

Next: guide 3, multi-tenant SaaS auth. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

Every login method fails somewhere, so pick the one whose failure you can explain to a user.

theAuth Guide: Cap Agent Spend and Require Human Approval

GDS K S — Sat, 10 Oct 2026 21:38:37 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

A planner agent of mine once fanned out to six workers on a Friday night. By Saturday morning one worker kept retrying a failed summarization, and my provider dashboard showed a line I did not like. Nobody broke in. Every credential was valid. The system simply had no idea that "valid" and "affordable" are different questions.

That weekend taught me that agent fleets need three controls beyond identity. Narrow grants that expire. A spend cap that actually stops calls. And a human checkpoint in front of the actions you cannot undo.

This guide builds all three with theAuth, an open-source auth library for AI agents and humans (@glinr/theauth on npm). By the end you will have a planner that delegates scoped, short-lived access to a worker, a budget guard that warns at one threshold and blocks at another, an approval flow for a destructive action, and a cost report that rolls up per delegation chain.

I already covered the basics of sub-agent delegation in an earlier post. This one starts where that one stopped: what happens to the money and the risky actions once the chain exists.

This is guide 6 of 8 in the theAuth guides. It stands on its own, so you can start right here. It uses agent identities from guide 5. If you already know how to create an agent, start here.

Guide	Title	Read it when
1	Add login to an existing Next.js app	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval (this guide)	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Control	What you call	What it does	Who enforces it
Delegation	`theauth.delegate()`	Grants a subset of permissions with an expiry and a depth cap	theAuth, inside `authorize()`
Budget policy	`theauth.policies.checkBudget()`	Reports whether a call would cross a limit	Your code
Approval	`theauth.approval.request()`	Stores a pending human decision	Your code
Cost attribution	`costs.recordCost()`	Records spend per agent, tool and chain	Your code, via alerts

Notice the last column. Only delegation and permission constraints sit inside authorize(). Budgets and approvals are modules you call. I will repeat this, because that wrong assumption causes most of the trouble.

Prerequisites

You need Node 20 or newer, a package manager, and a TypeScript project. You also need to know what an agent identity is in theAuth. If you do not, read the agent identity page first. It takes five minutes.

Install the package:

pnpm add @glinr/theauth

If you want a running app instead of a blank project, the quickstart has a one-command scaffolder. The examples below use SQLite so you can run them anywhere.

One honest scope note before we start. theAuth is a good fit when you want identity, scoped permissions and an audit trail in one place, in your own process and database. theAuth is not a billing system. It will not stop a provider from charging you, and it will not cap spend at the network level. Everything here works because your code asks the library first and obeys the answer.

Step 1: Create the fleet

Start with one instance and three agents. A planner holds the broad permissions. A summarizer starts with none and will receive access by delegation. A cleaner holds its own narrow permissions, including a delete that needs approval.

import { createTheAuth } from '@glinr/theauth';

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  approval: {
    ttl: 600, // seconds
    onApprovalNeeded: async (request) => {
      console.log(
        `[approval] ${request.agentId} wants to ${request.action} ${request.resource} (${request.id})`,
      );
    },
  },
});

const planner = await theauth.agent.create({
  ownerId: 'user-123',
  name: 'planner',
  type: 'autonomous',
  permissions: [
    { resource: 'mcp:github:*', actions: ['read', 'write', 'comment'] },
    { resource: 'mcp:linear:*', actions: ['read', 'write'] },
  ],
});

const summarizer = await theauth.agent.create({
  ownerId: 'user-123',
  name: 'summarizer',
  type: 'delegated',
  permissions: [],
});

The ownerId must match a real user row, so create or look up that user first. The agent identity docs show the full lifecycle, including token rotation. Each agent also gets a bearer token that appears once and sits hashed at rest. Put it in your secret store the moment you see it.

Why the delegated type for the summarizer? It signals intent. This agent exists to finish one task with borrowed access, then go away.

Step 2: Delegate the smallest useful grant

Now the planner hands the summarizer read access to GitHub issues, for 30 minutes, with no room for further hops.

const chain = await theauth.delegate({
  fromAgent: planner.id,
  toAgent: summarizer.id,
  permissions: [{ resource: 'mcp:github:issues', actions: ['read'] }],
  expiresAt: new Date(Date.now() + 30 * 60_000),
  maxDepth: 1,
});

console.log(chain.id, chain.depth); // dlg_..., 1

Three details in the delegation docs save real debugging time.

First, the subset rule. The planner must hold every permission it delegates. Asking for a wider resource or an action it lacks throws an error. That is the right failure: a compromised planner cannot mint power it never had.

Second, Each call checks maxDepth on its own. Later hops do not inherit it as a ceiling. To stop re-delegation, pass a small maxDepth on every delegate() call in your code. If you rely on a default of 3 somewhere, a chain can grow deeper than you planned.

Third, the subset check uses the delegating agent's own permissions. An agent that holds only delegated access cannot pass it on. If you want a middle agent to re-delegate, give it its own copy of the permissions. I find this surprising, but it errs on the safe side.

Check what the summarizer can actually do:

const allowed = await theauth.authorize(summarizer.id, {
  action: 'read',
  resource: 'mcp:github:issues',
});
// allowed.allowed === true

const denied = await theauth.authorize(summarizer.id, {
  action: 'write',
  resource: 'mcp:github:issues',
});
// denied.allowed === false

authorize() checks the agent's own permissions first, then falls back to delegated ones. You can list the delegated set directly:

const effective = await theauth.delegation.getEffectivePermissions(summarizer.id);
console.log(effective);

Revoking a chain

When a job goes wrong, you want one call that kills the whole subtree.

await theauth.delegation.revoke(chain.id);

Revoking a link also revokes active chains that start from the receiving agent. If the summarizer had delegated onward, those links die too. The next authorize() call returns allowed: false. One limit to remember: revocation does not interrupt an operation already in flight. A long HTTP request keeps running until it finishes.

Step 3: Put a budget in front of every LLM call

Delegation controls what an agent may touch. It says nothing about how much it may spend. For that, theAuth has budget policies on theauth.policies. Read the budget policies page once, because the model is specific.

Here is the part people miss. authorize() does not consult budget policies. Nothing happens unless your code calls checkBudget() before the LLM call and recordUsage() after it.

Create two policies for the summarizer, a soft one and a hard one:

await theauth.policies.create({
  agentId: summarizer.id,
  limits: { maxTokensCostPerDay: 800 },
  action: 'warn',
});

await theauth.policies.create({
  agentId: summarizer.id,
  limits: { maxTokensCostPerDay: 1000, maxCallsPerDay: 500 },
  action: 'block',
});

At 800 units the warn policy fires and checkBudget() still returns allowed: true, with the policy attached so you can alert someone. At 1000 the block policy returns allowed: false.

Now wrap your model call so the check is impossible to forget:

async function guardedCall<T>(
  agentId: string,
  estimatedCost: number,
  run: () => Promise<{ value: T; actualCost: number }>,
): Promise<T> {
  const check = await theauth.policies.checkBudget(agentId, estimatedCost);

  if (!check.allowed) {
    throw new Error(`Budget blocked for ${agentId}: ${check.reason}`);
  }
  if (check.reason) {
    console.warn(`[budget] soft limit reached for ${agentId}: ${check.reason}`);
  }

  const { value, actualCost } = await run();
  await theauth.policies.recordUsage(agentId, actualCost);
  return value;
}

Use it around any model call:

const summary = await guardedCall(summarizer.id, 50, async () => {
  const result = await llm.complete('Summarize the open issues.');
  return { value: result.text, actualCost: result.usage.totalTokens };
});

The llm object stands in for your own client. The wrapper only needs a number back.

Things that bite

The action field has four values: warn, throttle, block and revoke. In the current code, throttle, block and revoke all behave the same. Each returns allowed: false. revoke does not revoke the agent token for you. If you want the agent dead, call theauth.agent.revoke() yourself.

The check matches policies by agentId only. A policy with just a userId or tenantId has no agent, so it applies to every agent. Those two fields only work as list() filters, but they do not scope the check. If you plan a per-tenant cap, create one policy per agent and set the tenant field for filtering, rather than trusting it to do the matching. The multi-tenant page covers how tenants fit together.

Also, nothing resets counters on its own. You schedule that.

// UTC midnight cron
const { reset } = await theauth.policies.resetDaily();
console.log(`Reset ${reset} policies`);

// First of the month
await theauth.policies.resetMonthly();

Both calls apply to every policy. Policies that were triggered return to active once usage is back under the limit.

If you want hard call-count caps per agent per hour with no budget logic at all, the rate limiting page is the simpler tool.

Step 4: Require a human for the irreversible action

Budgets cap how much. Approval gates what. Some actions deserve a person saying yes first: deleting production files, moving money, widening permissions.

theAuth models this as a permission constraint, requireApproval. Give the cleaner agent a read permission and a delete permission that needs a human:

const cleaner = await theauth.agent.create({
  ownerId: 'user-123',
  name: 'file-cleaner',
  type: 'autonomous',
  permissions: [
    { resource: 'file:prod-data/*', actions: ['read'] },
    {
      resource: 'file:prod-data/*',
      actions: ['delete'],
      constraints: { requireApproval: true },
    },
  ],
});

When the cleaner tries to delete, authorize() denies it and says why. Your application spots that reason and opens an approval request. The approval docs describe the same flow.

async function tryDelete(path: string) {
  const attempt = {
    action: 'delete',
    resource: `file:prod-data/${path}`,
    arguments: { path: `/prod/${path}` },
  };

  const result = await theauth.authorize(cleaner.id, attempt);

  if (result.allowed) {
    return { done: true as const };
  }

  if (result.reason?.includes('requires human approval')) {
    const request = await theauth.approval.request({
      agentId: cleaner.id,
      userId: 'user-123',
      ...attempt,
    });
    return { done: false as const, approvalId: request.id };
  }

  throw new Error(`Denied: ${result.reason}`);
}

The agent does not block. It gets back an approvalId and moves on. The human answers minutes or hours later, within the TTL you set (the default is 5 minutes, and the config above raises it to 600 seconds).

Notify the human

theAuth stores the request. It does not deliver the message. You choose how a person finds out, with onApprovalNeeded (shown in Step 1) or a webhookUrl.

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  approval: {
    ttl: 300,
    webhookUrl: process.env.APPROVAL_WEBHOOK_URL,
  },
});

The webhook is a plain POST with an approval_needed event and the request body. It has no signature header and no retries. Treat it as a nudge, not a guarantee. If it fails, the request is still stored, and a periodic listPending() sweep will find it. Do not put anything secret in a handler that accepts that webhook without your own verification layer in front.

Approve, deny, and then actually act

Your backend exposes two routes. Pass the reviewer's identity so the record says who decided.

app.post('/approvals/:id/approve', async (req, res) => {
  const updated = await theauth.approval.approve(req.params.id, req.user.email);
  res.json({ status: updated.status });
});

app.post('/approvals/:id/deny', async (req, res) => {
  const updated = await theauth.approval.deny(req.params.id, req.user.email);
  res.json({ status: updated.status });
});

Now the part that trips people. Approval is a record, not a bypass. After a human approves, authorize() for that delete still returns allowed: false, because the permission still carries requireApproval. It does not look up approval rows.

Your code does the work itself once the status flips:

async function finishDelete(approvalId: string, path: string) {
  const request = await theauth.approval.get(approvalId);

  if (request?.status === 'approved') {
    await deleteFile(path); // your own code path, not authorize()
    return 'deleted';
  }
  if (request?.status === 'denied') return 'denied';
  return 'still pending or expired';
}

Make that function the only place the delete happens. If a second code path can delete without checking approval status, you have built a checkbox, not a gate.

Two smaller facts. approve() and deny() throw unless the request is pending. And approve() does not check expiresAt. A request past its TTL stays pending until you run cleanup, so schedule it:

const { expired } = await theauth.approval.cleanup();
console.log(`Expired ${expired} stale approval requests`);

Pair this with a UI that lists listPending(userId), and a reviewer sees exactly what the agent wanted, with its arguments, before saying yes.

Step 5: Attribute every dollar

The budget policy counts whatever number you hand it. It does not tell you which tool burned the money or which delegation chain a job belonged to. For that you want cost attribution. See the cost attribution page.

This module is standalone. You build it from the database handle:

import { createCostAttributionModule } from '@glinr/theauth/auth';

const costs = createCostAttributionModule(theauth.db, {
  currency: 'USD',
  retentionDays: 90,
  alertThresholds: { warn: 5.0, critical: 20.0 },
  onAlert: async (alert) => {
    console.warn(
      `[cost] ${alert.type} agent=${alert.agentId} spent=$${alert.currentCostUsd.toFixed(4)} limit=$${alert.threshold} period=${alert.period}`,
    );
    if (alert.type === 'budget_exceeded') {
      await theauth.agent.revoke(alert.agentId);
    }
  },
});

Record each call with the chain ID, so a job's cost rolls up no matter which sub-agent spent it:

await costs.recordCost({
  agentId: summarizer.id,
  tool: 'openai:gpt-4o-mini',
  inputTokens: 1200,
  outputTokens: 300,
  costUsd: 0.0004,
  delegationChainId: chain.id,
  metadata: { job: 'nightly-issue-digest' },
});

Later, ask what the whole chain cost:

const report = await costs.getDelegationChainCost(chain.id);
if (report.success) {
  console.log(report.data.totalCostUsd.toFixed(4));
  console.log(report.data.byTool);
}

Every method returns a Result object, so check success before reading data. Other useful reads are getAgentCost(), getOwnerCost() and getTopAgentsByCost(10). The last one answers the question I was asking that Saturday: which agent did this.

Alert behavior to plan around

Alerts are level-triggered. While spend sits above a threshold, every recordCost() call fires the alert again. If you page a human from onAlert, deduplicate first. A simple in-memory set keyed by agent and alert type works until you run more than one process, and then you want a shared store.

The warn and critical thresholds look at a 24-hour rolling window. The budget_exceeded alert compares calendar-month spend against the smallest maxTokensCostPerMonth among that agent's policies.

The cost module's checkBudget() is a separate function from the policy one:

const status = await costs.checkBudget(summarizer.id);

if (status.success && !status.data.withinBudget) {
  throw new Error('Monthly cost budget reached');
}

It reads only the monthly token-cost limit and ignores the policy action. It also skips policies that have no matching agentId. Keep your units straight. If you pass dollars to recordCost() and tokens to recordUsage(), the two systems will agree on nothing. Pick one unit for the limits (I use dollars) and feed both modules in that unit.

Step 6: One guard for everything

Here is the shape I ship. A single function does the budget check, the model call, the cost record and the usage record, in that order. Agents call this and nothing else.

async function runModelCall(opts: {
  agentId: string;
  chainId: string;
  tool: string;
  estimateUsd: number;
  call: () => Promise<{ text: string; inTok: number; outTok: number; usd: number }>;
}): Promise<string> {
  const policy = await theauth.policies.checkBudget(opts.agentId, opts.estimateUsd);
  if (!policy.allowed) throw new Error(`Policy blocked: ${policy.reason}`);

  const monthly = await costs.checkBudget(opts.agentId);
  if (monthly.success && !monthly.data.withinBudget) {
    throw new Error('Monthly cost budget reached');
  }

  const out = await opts.call();

  await costs.recordCost({
    agentId: opts.agentId,
    tool: opts.tool,
    inputTokens: out.inTok,
    outputTokens: out.outTok,
    costUsd: out.usd,
    delegationChainId: opts.chainId,
  });
  await theauth.policies.recordUsage(opts.agentId, out.usd);

  return out.text;
}

Yes, there are two budget checks. They read different counters, and I would rather block on either than discover a gap at 2 a.m. Duplicated bookkeeping is the price of two modules that were not built to share a counter.

One race to know about. Two parallel calls can both pass checkBudget() before either records usage, so a hard cap can overshoot by the cost of the calls in flight. If that matters, serialize calls per agent or pass a generous estimateUsd.

Step 7: Agents that call other agents

Up to here, the fleet lives in one process. Once agents sit in different services, you need them to authenticate to each other. theAuth ships an A2A server and client for the Google Agent-to-Agent protocol, and the A2A page documents both.

The server side validates the caller's bearer token with the same identity system:

import { createAgentCard, createA2AServer } from '@glinr/theauth/a2a';

const card = createAgentCard({
  agent: { id: summarizer.id, name: summarizer.name, type: summarizer.type },
  url: process.env.A2A_PUBLIC_URL!,
  description: 'Summarizes issues and threads',
  version: '1.0.0',
  skills: [
    {
      id: 'summarize',
      name: 'Summarize',
      description: 'Condenses a thread into key points',
      tags: ['summary'],
    },
  ],
  securitySchemes: {
    bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
  },
  security: [{ bearer: [] }],
});

const server = createA2AServer({
  agentCard: card,
  handler: { onMessage: handleSummarizeMessage },
  authenticate: async (request) => {
    const token = request.headers.get('Authorization')?.replace('Bearer ', '');
    if (!token) return null;
    const caller = await theauth.agent.validateToken(token);
    return caller?.id ?? null;
  },
  onAudit: async (event) => {
    console.log('[a2a]', event.method, event.agentId, event.success);
  },
});

Mount server.handleRequest(req) on /a2a and on /.well-known/agent.json. The handleSummarizeMessage function is yours: it receives the message and returns a task object. Inside it, call runModelCall from Step 6, so remote traffic hits the same budget guard as local traffic.

Two cautions from the docs. If you omit authenticate, the server accepts unauthenticated calls. And the default task store is an in-memory map, so tasks vanish on restart. Pass a taskStore of your own for anything real.

A2A authentication proves who is calling. It does not carry delegation by itself. If a remote agent should act with narrowed rights, create the delegation on your side and record costs against its chain ID as before.

A worked failure, start to finish

Here is how the pieces behave together when something goes wrong. Say the summarizer enters a retry loop at 02:10.

The loop calls runModelCall() again and again. Each pass runs checkBudget(), makes the call, records cost against the chain, and records usage. At 800 units the warn policy attaches a reason, and your logger prints a soft-limit line. Nobody is awake to read it, so nothing changes.

At 24-hour spend of $5, the cost module fires a warn alert. At $20 it fires critical. Your onAlert handler pages the on-call person, and because alerts repeat on every recorded cost, the page needs deduplication or it will ring 40 times.

At 1000 units the block policy returns allowed: false and the guard throws. The loop dies on its next iteration. The agent is still alive, still holds its delegation, and still passes authorize(). Only the spending stopped.

That gap matters. A budget stop and an access stop are different levers. If you also want access gone, revoke the chain with theauth.delegation.revoke(chain.id) or revoke the agent with theauth.agent.revoke(). I wire the budget_exceeded alert to the agent revoke, and I leave the chain revoke as a deliberate human action so a legitimate big job does not lose its whole tree to one noisy night.

Compare that with the approval path. If the same runaway loop tried a delete, the first attempt would create one request. A loop that retries the delete creates one new request per attempt, unless you remember the approvalId and check get() first. Keep a map from the attempted action to its pending request, and return the existing ID on a repeat. Otherwise your reviewer opens their queue to 300 identical rows.

Test the guard before you trust it

I do not believe a budget guard until I have watched it block. Write a throwaway script that spends a 3 unit budget on purpose.

const probe = await theauth.agent.create({
  ownerId: 'user-123',
  name: 'budget-probe',
  type: 'autonomous',
  permissions: [],
});

await theauth.policies.create({
  agentId: probe.id,
  limits: { maxTokensCostPerDay: 3 },
  action: 'block',
});

for (let i = 1; i <= 5; i++) {
  const check = await theauth.policies.checkBudget(probe.id, 1);
  console.log(`call ${i}: allowed=${check.allowed}`);
  if (check.allowed) await theauth.policies.recordUsage(probe.id, 1);
}

You should see calls 1 to 3 pass and calls 4 and 5 fail. If call 4 passes, your units or your recordUsage() call are wrong. Fix that before you wire the guard into real agents.

Do the same for approvals. Create a request, confirm listPending() returns it, approve it, and confirm get() reports approved. Then call authorize() on the same delete and watch it deny. Seeing that denial once will save you from writing the wrong code path later.

Running it in production

A handful of habits keep this setup honest after the demo.

Schedule four jobs. Run resetDaily() at UTC midnight and resetMonthly() on the first of the month. Run approval.cleanup() every 5 minutes so stale requests flip to expired. Run costs.cleanup() nightly so cost events respect your retention window.

Log the auditId that authorize() returns next to your own request IDs. When a human asks why an agent did something, the audit trail gives you the decision and you give them the context.

Review the top spenders weekly with getTopAgentsByCost(10). In my fleet, one agent costs more than the other nine put together, and the culprit never matched my guess.

Finally, set the delegation expiry to the length of the job, not the length of the day. A 30-minute task gets a 30-minute grant. When the grant lapses, the access lapses with it, and you did not have to remember anything.

Troubleshooting and gotchas

The agent keeps spending after the cap

Check that your code calls checkBudget() before the model call and acts on allowed: false. The library will not intercept your HTTP client. This is the cause nine times out of ten.

A policy for one user caps everyone

Policies with only userId or tenantId apply to all agents, since the check matches on agentId alone. Add an agentId to every policy you create. List your policies with theauth.policies.list() and look for entries without one.

An approved delete is still denied

Expected. authorize() never consults approval records. Run the action from your own code path after reading the approval status, as in Step 4.

Approvals sit pending forever

Nothing expires them until cleanup() runs. Schedule it. Also remember that approve() accepts a request that is past its TTL if cleanup has not run yet. If that matters, compare expiresAt yourself before acting.

Re-delegation throws a subset error

The middle agent holds only delegated permissions. Give it its own copy of the permissions it needs to pass on, then pass a maxDepth that covers the new hop.

Alerts fire in a loop

They are level-triggered. Deduplicate in onAlert, or revoke the agent on budget_exceeded so spend stops growing.

Counters never go back down

You did not schedule resetDaily() and resetMonthly(). No one does it for you.

When this is the wrong tool

If you need spend caps enforced at a gateway for every service in your company, use a gateway or your provider's own quotas. This guide gives you an application-level guard. It protects only the code paths that call it.

If you need signed webhooks with retries for approval delivery, put a queue in front of the approval hook. The built-in webhook is a simple fire-and-forget POST.

If your fleet is a single agent with one tool, delegation is overhead. Start with a permission and a budget policy and add the rest when a second agent shows up.

Go deeper

The pages I used most while building this, in the order I would read them:

Delegation chains for subset rules, depth and cascading revocation
Budget policies for limits, actions and resets
Approval flows for requests, webhooks and cleanup
Cost attribution for reports, alerts and chain costs
A2A protocol for agent cards and authenticated agent-to-agent calls
Permissions for resources, actions and constraints
Audit trail for the authorization log
Trust scoring for deciding which agents earn which permissions
Quickstart for a first working project

FAQ

Does theAuth stop an agent from overspending automatically?

No. Budget policies report a result, and your code must act on it. Call checkBudget() before each model call and recordUsage() after. The authorize() method does not read budget policies.

What happens to sub-agents when I revoke a delegation?

Revoking a chain also revokes active chains that start from the receiving agent. Their next authorize() call returns allowed: false. Operations already running are not interrupted.

Can an agent bypass requireApproval after a human approves?

The permission is still denied by authorize() even after approval. Approval is a stored record. Your application performs the action once the status reads approved, so keep that as the single code path.

How do I see what one job cost across five agents?

Pass the same delegationChainId to recordCost() for every call, then read getDelegationChainCost(chainId). The report groups spend by tool for that chain.

How deep can a delegation chain go?

The default maxDepth is 3, and each delegate() call tests against the value you pass on that call. Hops do not inherit it, so pass a small one on every hop you create.

Do I need A2A to use delegation, budgets or approval?

No. Those three work inside one process. A2A matters when agents run in separate services and need to authenticate each other.

What is the one action in your agent fleet that you would never let run without a human, and where does that check live today?

Try it yourself

Next: guide 7, securing an MCP server. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

An agent with a valid token and no budget is just an expensive typo waiting to happen.

theAuth: Add Login to an Existing Next.js App

GDS K S — Sat, 10 Oct 2026 20:40:52 +0000

theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev

Last month I opened a side project I had shipped with no login at all. Every page was public, every API route trusted whoever called it. I had told myself I would "add auth later," and later arrived the day a friend pasted my admin URL into a group chat.

Adding auth to a running app is a different job from starting a new one. You have routes, layouts, and data that already exist. You cannot scaffold your way out of it. You need a small, boring set of changes that you can read in one sitting and undo if they go wrong.

This guide walks that path with theAuth, an open-source TypeScript auth library that also handles AI agent identity. We will add username and password login, cookie sessions, and protected pages to a Next.js App Router app. I wrote it from the docs and the package source, so every import and option below exists in the code. Where a feature is missing or rough, I say so.

This is guide 1 of 8 in the theAuth guides. It stands on its own, so you can start right here. Nothing comes before it. If you build for AI agents rather than people, jump to guide 5.

Guide	Title	Read it when
1	Add login to an existing Next.js app (this guide)	You have an app with no auth yet
2	Passwordless login: passkeys, links, OTP	You want to drop passwords or add 2FA
3	Multi-tenant SaaS auth: orgs, RBAC, SSO, SCIM	You sell to teams and companies
4	Migrate from Auth0 or Clerk	You already run another provider
5	Give every AI agent its own identity	You run AI agents and need to start somewhere
6	Cap agent spend and require human approval	Your agents spend money or act on risky things
7	Secure an MCP server for production	You expose tools over MCP
8	Build an audit trail for AI agent actions	Someone will ask what your agents did

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches.

TL;DR

Step	What you do	Where
1	Install `@glinr/theauth`	terminal
2	Add a 32+ character session secret	`.env.local`
3	Create one shared instance and session manager	`lib/theauth.ts`
4	Add sign-up, sign-in, and sign-out route handlers	`app/api/account/*`
5	Read the session in server code	`lib/auth.ts`
6	Guard pages with middleware plus a server check	`middleware.ts`, `app/dashboard`
7	Build the forms and run the first login	`app/sign-in`, `app/sign-up`

Expect about 150 lines of code in total. You will touch six or seven files and add zero new database tables by hand.

What you need first

You need an existing Next.js app on the App Router. The @glinr/theauth-nextjs adapter declares next >= 14 as its peer dependency. The code in this guide uses the async headers() function from Next.js 15, so on 14 you drop the await.

You need Node.js 18 or later and a package manager. I use pnpm. The commands translate to npm or yarn without changes.

You need a database. SQLite works for local development and needs no setup. For production, plan on Postgres (or MySQL, or D1 on Cloudflare). theAuth creates its own tables with a theauth_ prefix next to yours, so it does not touch your schema.

One honest note before you invest an hour. theAuth takes an agent-first approach to design. Its built-in human sign-in is username and password, not email and password, and it ships headless: no prebuilt login page, no social buttons wired by default. If you want email sign-in with a hosted UI in ten minutes, Clerk or Auth.js will get you there faster. If you want one library that also issues identities to your AI agents later, keep reading. I cover this tradeoff again near the end.

Step 1: Install the packages

pnpm add @glinr/theauth

That one package carries the core, the SQLite driver (sql.js, compiled to WebAssembly), the username module, and the session managers. For Postgres, add the pg driver as well:

pnpm add pg
pnpm add -D @types/pg

The database driver is an optional peer dependency, so theAuth only loads it when you pick that provider. If you forget it, you get a clear startup error that names the missing package. The database setup page lists the driver for each provider, including the native SQLite option that needs a C++ build step.

You do not need @glinr/theauth-nextjs yet. That adapter mounts agent and MCP endpoints, not human login. I come back to it in step 8.

Step 2: Add the secrets

Generate a session secret and put it in .env.local:

openssl rand -base64 32

# .env.local
SESSION_SECRET=paste-the-generated-value-here
APP_HOST=localhost:3000
# Production only: your public host name and database
# APP_HOST=app.example.com
# DATABASE_URL=postgresql://user:password@host:5432/dbname

The secret signs every session token, and theAuth rejects anything under 32 characters. Keep this value stable across deploys. A new secret invalidates every cookie already out there, which signs all your users out at once. The cookie options page says plainly that theAuth does not support a list of secrets for rotation, so plan any change for a quiet hour.

Step 3: Create one shared instance

Create two files. The first holds the cookie name and the app origin in a short module, so the middleware can import them later without pulling in a database driver. The second, lib/theauth.ts, builds the theAuth instance and the cookie session manager once per process.

// lib/constants.ts
export const SESSION_COOKIE = 'theauth_session';

const scheme = process.env.NODE_ENV === 'production' ? 'https' : 'http';
export const BASE_URL = `${scheme}://${process.env.APP_HOST ?? 'localhost:3000'}`;

// lib/theauth.ts
import { createCookieSessionManager, createTheAuth } from '@glinr/theauth';
import { BASE_URL, SESSION_COOKIE } from './constants';

const isProd = process.env.NODE_ENV === 'production';

async function init() {
  const theauth = await createTheAuth({
    database: isProd
      ? { provider: 'postgres', url: process.env.DATABASE_URL! }
      : { provider: 'sqlite', url: './theauth-dev.db' },
    baseUrl: BASE_URL,
    auth: {
      session: { secret: process.env.SESSION_SECRET!, cookieName: SESSION_COOKIE },
    },
    username: {},
  });

  if (!theauth.username) {
    throw new Error('The username module did not start. Check auth.session.');
  }

  const sessions = createCookieSessionManager(
    {
      secret: process.env.SESSION_SECRET!,
      sessionName: SESSION_COOKIE,
      maxAge: 7 * 24 * 60 * 60,
      autoRefresh: false,
      cookieOptions: { httpOnly: true, secure: isProd, sameSite: 'lax', path: '/' },
    },
    theauth.db,
  );

  return { theauth, username: theauth.username, sessions };
}

type TheAuthContext = Awaited<ReturnType<typeof init>>;

const globalForTheAuth = globalThis as typeof globalThis & {
  theauthContext?: Promise<TheAuthContext>;
};

export function getTheAuth(): Promise<TheAuthContext> {
  globalForTheAuth.theauthContext ??= init();
  return globalForTheAuth.theauthContext;
}

Four choices in that file deserve a closer look.

First, createTheAuth is async, so you cannot export a ready instance from a plain module without top-level await. The getTheAuth() function stores the promise on globalThis. In development, Next.js reloads modules often, and without the global you would open a new database connection on every edit.

Second, the session secret lives at auth.session.secret. The configuration reference notes that the config type has a top-level secret option, yet createTheAuth() never reads it. Some of the shorter examples in the docs pass it anyway. Ignore that and use auth.session.

Third, username: {} turns on the username module with its defaults: 3 to 32 characters for usernames, 8 to 128 for passwords. The module is null unless auth.session is also set, which is why I throw when it comes back empty.

Fourth, autoRefresh: false. I explain this one in the gotchas, because it cost me the most thinking. Short version: server components cannot set cookies, and the refresh feature needs to.

On first start, theAuth runs CREATE TABLE IF NOT EXISTS for its tables. You do not run a migration command. If you manage schema changes yourself with another tool, set skipMigrations: true inside database. The database page covers the tradeoff: auto-migration only creates missing tables and never alters existing ones.

Step 4: Sign-up, sign-in, and sign-out routes

The username module has a built-in handleRequest that expects paths like /auth/username/sign-up. The Next.js adapter does not route to it, so I call the typed methods directly from my own route handlers. That gives me full control over cookies and error codes, and it keeps the code short.

First, a small helper that turns a sign-in result into a cookie. Put it in lib/session.ts:

// lib/session.ts
import { getTheAuth } from './theauth';

interface SignedIn {
  user: { id: string; username: string };
  session: { token: string };
}

export async function issueSession(result: SignedIn, req: Request): Promise<string> {
  const { sessions } = await getTheAuth();

  // signUp and signIn each mint a session of their own.
  // Drop it and issue one through the cookie manager so we control the metadata.
  const minted = await sessions.raw.validate(result.session.token);
  if (minted) await sessions.revokeSession(minted.id);

  const { setCookieHeader } = await sessions.createSession(result.user.id, {
    username: result.user.username,
    userAgent: req.headers.get('user-agent') ?? 'unknown',
  });

  return setCookieHeader;
}

Why the extra revoke? The username module returns a session token in its JSON, not a cookie. I want a cookie with HttpOnly, SameSite, and my own metadata on the row. Revoking the module's session and creating one through the cookie manager costs one extra insert and one delete per login. It also means I can read session.metadata.username later without another database query. The sessions page documents createSession and its metadata argument.

Now the sign-up route:

// app/api/account/sign-up/route.ts
import { NextResponse } from 'next/server';
import { issueSession } from '@/lib/session';
import { getTheAuth } from '@/lib/theauth';

export async function POST(req: Request) {
  const body = (await req.json()) as { username?: string; password?: string; name?: string };

  if (!body.username || !body.password) {
    return NextResponse.json({ error: 'Username and password are required' }, { status: 400 });
  }

  const { username } = await getTheAuth();

  try {
    const result = await username.signUp({
      username: body.username,
      password: body.password,
      name: body.name,
    });
    const setCookie = await issueSession(result, req);

    return NextResponse.json({ user: result.user }, { status: 201, headers: { 'Set-Cookie': setCookie } });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Sign-up failed';
    return NextResponse.json({ error: message }, { status: 400 });
  }
}

signUp throws with a readable message when the username already exists, runs too short, or contains characters outside the allowed pattern. The route passes that message through as a 400, which suits a form. The username page lists each rule and how to change the limits.

Sign-in follows the same shape, with one difference in how it handles failure:

// app/api/account/sign-in/route.ts
import { NextResponse } from 'next/server';
import { issueSession } from '@/lib/session';
import { getTheAuth } from '@/lib/theauth';

export async function POST(req: Request) {
  const body = (await req.json()) as { username?: string; password?: string };

  if (!body.username || !body.password) {
    return NextResponse.json({ error: 'Username and password are required' }, { status: 400 });
  }

  const { username } = await getTheAuth();

  try {
    const result = await username.signIn({ username: body.username, password: body.password });
    const setCookie = await issueSession(result, req);

    return NextResponse.json({ user: result.user }, { headers: { 'Set-Cookie': setCookie } });
  } catch {
    return NextResponse.json({ error: 'Invalid username or password' }, { status: 401 });
  }
}

I return the same generic message for every failure. The module itself throws one message for an unknown username and another for a wrong password path, and a third for a forced password reset. Collapsing them in the route stops an attacker from using your login form to find valid usernames. If you plan to use the forced reset feature, split that case out so those users learn why they cannot sign in.

Sign-out revokes the row and clears the cookie:

// app/api/account/sign-out/route.ts
import { NextResponse } from 'next/server';
import { getTheAuth } from '@/lib/theauth';

export async function POST(req: Request) {
  const { sessions } = await getTheAuth();
  const { session } = await sessions.validateSession(req.headers.get('cookie') ?? '');

  if (session) await sessions.revokeSession(session.id);

  return new NextResponse(null, {
    status: 204,
    headers: { 'Set-Cookie': sessions.buildLogoutCookie() },
  });
}

Revocation deletes the session row, so the token stops working at once even if someone copied it. That is the main reason to keep sessions in the database instead of using bare JWTs. The JWT sessions page covers the stateless alternative for mobile apps and separate API origins, where cookies do not fit.

Step 5: Read the session in server code

Every protected page and route handler needs the same question answered: who is this? Put the answer in one file, lib/auth.ts:

// lib/auth.ts
import { headers } from 'next/headers';
import { redirect } from 'next/navigation';
import { getTheAuth } from './theauth';

export interface CurrentUser {
  id: string;
  username: string;
  sessionId: string;
}

export async function getCurrentUser(): Promise<CurrentUser | null> {
  const { sessions } = await getTheAuth();
  const cookieHeader = (await headers()).get('cookie') ?? '';
  const { session } = await sessions.validateSession(cookieHeader);

  if (!session) return null;

  return {
    id: session.userId,
    username: String(session.metadata?.username ?? ''),
    sessionId: session.id,
  };
}

export async function requireUser(): Promise<CurrentUser> {
  const user = await getCurrentUser();
  if (!user) redirect('/sign-in');
  return user;
}

validateSession takes the raw Cookie header and returns { session, refreshCookieHeader }. The session is null when the cookie is missing, malformed, expired, or revoked. The call returns no error code to branch on, which keeps the call site simple: either you have a session or you do not.

The user.id is the value to store in your own tables. If your app already has a projects table with an owner column, new rows get user.id there. Because theAuth stores its users in theauth_users, your existing tables stay as they are, and you add a foreign key from your tables to that ID only if you want one.

Step 6: Protect routes in two layers

Protection needs two layers, and the first one is not security.

Layer one: middleware as a fast redirect

Middleware runs before the page renders and often on the edge runtime, where a database driver may not work. I use it only to send visitors without a cookie to the sign-in page. Anyone can forge a cookie, so this check proves nothing. It just saves a render.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';
import { SESSION_COOKIE } from '@/lib/constants';

export function middleware(req: NextRequest) {
  if (!req.cookies.has(SESSION_COOKIE)) {
    return NextResponse.redirect(new URL('/sign-in', req.url));
  }
  return NextResponse.next();
}

export const config = { matcher: ['/dashboard/:path*'] };

The cookie name comes from lib/constants.ts on purpose. Importing it from lib/theauth.ts would drag the database driver into the middleware bundle, and the build fails with a confusing driver error. Newer Next.js releases also renamed the middleware file convention, so check what your installed version expects.

Layer two: the real check on the server

The second layer is the one that counts. Every page and handler that returns private data calls requireUser() or getCurrentUser() itself. A dashboard page looks like this:

// app/dashboard/page.tsx
import { requireUser } from '@/lib/auth';
import { SignOutButton } from './sign-out-button';

export default async function DashboardPage() {
  const user = await requireUser();

  return (
    <main>
      <h1>Dashboard</h1>
      <p>Signed in as {user.username}</p>
      <SignOutButton />
    </main>
  );
}

And a protected API route returns 401 instead of redirecting:

// app/api/projects/route.ts
import { NextResponse } from 'next/server';
import { getCurrentUser } from '@/lib/auth';

export async function GET() {
  const user = await getCurrentUser();
  if (!user) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });

  // Query your own tables with user.id here.
  return NextResponse.json({ projects: [], ownerId: user.id });
}

Keep the rule simple. Middleware may redirect, but only the server check may return data. If you delete the middleware file tomorrow, nothing leaks.

Step 7: Build the forms and run the first login

Two client components and one small button. Start with the sign-in form:

// app/sign-in/page.tsx
'use client';

import { useState } from 'react';
import { useRouter } from 'next/navigation';

export default function SignInPage() {
  const router = useRouter();
  const [error, setError] = useState<string | null>(null);
  const [pending, setPending] = useState(false);

  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setPending(true);
    setError(null);

    const form = new FormData(event.currentTarget);
    const res = await fetch('/api/account/sign-in', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        username: form.get('username'),
        password: form.get('password'),
      }),
    });

    setPending(false);

    if (!res.ok) {
      const data = (await res.json()) as { error?: string };
      setError(data.error ?? 'Sign-in failed');
      return;
    }

    router.push('/dashboard');
    router.refresh();
  }

  return (
    <form onSubmit={onSubmit}>
      <label>
        Username
        <input name="username" autoComplete="username" required />
      </label>
      <label>
        Password
        <input name="password" type="password" autoComplete="current-password" required />
      </label>
      {error && <p role="alert">{error}</p>}
      <button type="submit" disabled={pending}>
        {pending ? 'Signing in...' : 'Sign in'}
      </button>
    </form>
  );
}

The sign-up page is the same form posting to /api/account/sign-up with an extra name input, so I will not paste it twice. Copy the file, swap the URL, add the field, and set autoComplete="new-password" on the password input.

The sign-out button is a short client component:

// app/dashboard/sign-out-button.tsx
'use client';

import { useRouter } from 'next/navigation';

export function SignOutButton() {
  const router = useRouter();

  async function onClick() {
    await fetch('/api/account/sign-out', { method: 'POST' });
    router.push('/sign-in');
    router.refresh();
  }

  return <button onClick={onClick}>Sign out</button>;
}

Now run the first login. Start the dev server with pnpm dev, then try the whole loop from a terminal. This tests the server without any UI getting in the way:

# Create an account and save the cookie
curl -i -c jar.txt -X POST localhost:3000/api/account/sign-up \
  -H 'Content-Type: application/json' \
  -d '{"username":"ada_lovelace","password":"correct horse battery","name":"Ada"}'

# Call a protected page with the cookie
curl -s -b jar.txt localhost:3000/dashboard | grep "Signed in as"

# Call it without the cookie
curl -i localhost:3000/dashboard

The first call should return 201 with a Set-Cookie: theauth_session=... header that includes HttpOnly and SameSite=Lax. The second should print the line Signed in as ada_lovelace. The third should return a redirect to /sign-in. If all three behave, open the browser, visit /sign-up, create a second account, and watch the dashboard load.

You will also see a theauth-dev.db file appear in your project root. Add it to .gitignore now.

Step 8: Optional, mount the adapter for agents

Everything above handles humans. If you also want to issue identities to AI agents later, the adapter is where that lives. Install it and mount the catch-all route:

pnpm add @glinr/theauth-nextjs

// app/api/theauth/[...theauth]/route.ts
import { theAuthNextjs } from '@glinr/theauth-nextjs';
import { getTheAuth } from '@/lib/theauth';

const { theauth } = await getTheAuth();
const handlers = theAuthNextjs(theauth);

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;

You must also add agents: { enabled: true } to the createTheAuth call in lib/theauth.ts. That option is what creates the agent, permission, delegation, and audit tables. Without it, agent.create fails.

Read the next sentence twice. The route handler exposes theAuth's REST endpoints and does not add authentication of its own. The add-to-existing-app guide says so directly. If you mount it, protect /api/theauth/* with your own check, for example by calling getCurrentUser() in a wrapper. Do not leave it open because "nobody knows the path."

The Next.js adapter page lists every endpoint it serves, including the optional MCP OAuth endpoints. If you only need human login, skip this step entirely.

Gotchas and troubleshooting

Users keep getting signed out after one page load

This is the autoRefresh trap. With autoRefresh: true, every successful validateSession call deletes the session row and creates a new one, then hands you the new cookie in refreshCookieHeader. A Server Component cannot set cookies. The row gets replaced, the browser keeps the old cookie, and the next request fails.

You have two fixes. Turn autoRefresh off, as in step 3, and accept a fixed 7-day lifetime from sign-in. Or keep it on and call validateSession only in places that can write headers, such as route handlers and middleware, then forward refreshCookieHeader yourself. I picked the first option because it has no moving parts. The cookie options page shows the trade.

`theauth.username` is null

It stays null unless two things are true: you passed a username key, and you configured auth.session. Missing either one gives you a null module with no error, which is why lib/theauth.ts checks for it and throws.

The sign-in works locally and fails on HTTPS

The cookie manager sets Secure based on NODE_ENV, not on your URL. If your host does not set NODE_ENV=production, browsers get a cookie without Secure, or you get one with Secure over plain HTTP and the browser drops it. Set cookieOptions.secure explicitly, as step 3 does.

The React provider keeps failing to sign in

@glinr/theauth-react ships TheAuthProvider, useUser, and useSignIn. In its managed mode, those hooks post to {basePath}/auth/sign-in with an email and password. theAuth core does not serve a route at that path. The React page says this in a warning box. That is why this guide uses plain forms.

You have two options if you want the hooks. Serve the routes the provider expects from your own handler, or use the provider's external mode and point mePath and logoutPath at your own API. I have not built a full flow on external mode for this guide, so test it before you rely on it.

Rate limits do not cover my routes

The rateLimit() plugin applies per-IP limits to /auth/* endpoints that theAuth itself serves. My /api/account/* handlers are plain Next.js routes, and I found nothing in the source that wraps them. Add limits at your edge, in your host's firewall, or with your own counter. A login form with no throttle invites password guessing. The rate limiting page explains what the plugin does cover.

CSRF on cookie sessions

SameSite=Lax blocks the common cross-site POST. For a second layer, the session helpers export validateOrigin, which checks the Origin header against a list you trust. Call it at the top of each mutating route:

import { validateOrigin } from '@glinr/theauth';
import { BASE_URL } from '@/lib/constants';

const origin = validateOrigin(req, [BASE_URL]);
if (!origin.valid) {
  return NextResponse.json({ error: 'Origin not allowed' }, { status: 403 });
}

The sessions page also documents a double-submit CSRF token for stricter setups.

Placeholder emails in `theauth_users`

The username module has no email field in its flow. In the source, signUp writes <username>@username.local into the email column of theauth_users. Nothing breaks, but do not send mail to that address, and do not show it to users. If you need real emails, pair the module with the email verification module or switch to the magic link flow.

SQLite files and more than one process

The sqlite provider keeps the database in memory and rewrites the whole file after each write. The database page warns against pointing two or more processes at one file. In practice that means do not run next dev and a second script against the same theauth-dev.db. Use Postgres anywhere that matters.

Is this the right fit?

Choose theAuth for this job if you want username and password login you fully control, sessions you can revoke in one query, and a path to agent identities, delegation, and audit logs in the same library. You own the forms, the routes, and the error messages.

Choose something else if you need these today. Email and password with verified addresses and password reset emails, out of the box. Prebuilt sign-in components. A hosted dashboard for end users. Social login with five providers and no wiring. Clerk, Auth.js, or better-auth cover that ground with less code. The theAuth docs even include a migration section for people moving between libraries, and the add-to-existing-app guide shows theAuth running next to Clerk or Auth.js for the agent side only.

One more limit worth stating. I did not find a documented way to import existing password hashes into the username module. If your app already has users with passwords, plan on asking them to sign up again or reset, or run a parallel period where both systems work.

Go deeper

Each page below maps to a piece of this guide:

Quickstart for the template scaffolder and the agent path.
Add to an existing app for running theAuth beside Clerk, Auth.js, or better-auth.
Session model for freshness guards, CSRF, and revoking all sessions.
Cookie options for cross-subdomain cookies and the Secure default.
JWT sessions for mobile apps and separate API origins.
Multi-session for device lists and session caps.
Database setup for providers, drivers, and the full table list.
Configuration for every createTheAuth() option.
Username and password for limits, patterns, and password changes.
Magic link and two-factor auth for the next layer of login.
Rate limiting for the plugin and its limits.
React hooks and the Next.js adapter for client state and agent endpoints.

FAQ

Does theAuth replace my existing login?

Only if you want it to. The add-to-existing-app guide runs theAuth next to Clerk, Auth.js, or better-auth, using your current user ID as the owner of agents. This guide goes the other way and uses theAuth's own username module for human login.

Can users sign in with an email address?

Not with the built-in password module, which is username based. Use the magic link or email OTP modules for email-first sign-in. Both need auth.session and an email-sending callback that you write.

Which database should I use in production?

Postgres, MySQL, or D1 on Cloudflare. The SQLite providers work for local development and small single-process deploys. Install the matching driver (pg or mysql2) yourself, because theAuth loads it on demand.

How long does a session last?

Seven days by default (maxAge of 604,800 seconds). With autoRefresh off, as in this guide, the session ends 7 days after sign-in no matter how active the user is. Change maxAge on the cookie session manager to adjust it.

Can I check sessions in middleware on the edge runtime?

Session validation reads the database, so it does not fit an edge middleware that cannot reach your driver. Use middleware for a cookie presence check and redirect, then check the session in server components and route handlers where the driver works.

How do I add AI agents later?

Add agents: { enabled: true } to the config, then call theauth.agent.create with the user.id as ownerId. Agents get bearer tokens, scoped permissions, and audit entries. The quickstart page walks through the first agent in five short steps.

Your turn

When you added auth to an app that was already live, what broke first: the cookies, the redirects, or the existing users? I would like to know which of the gotchas above hit you, and which one I missed.

Try it yourself

Next: guide 2, passwordless login. The full list sits in the table at the top of this page.

GDS K S · thegdsks.com · building Glincker · follow on X @thegdsks

Ship the login first, then give your agents their own identity so a leaked admin URL stops being your only defense.