Get started
Pick a track: people signing in, or agents calling.
Most apps need both. A person logs in and gets a session. An AI agent, an MCP client or a script presents a scoped token instead. theAuth handles each with its own mechanism, in one library, in TypeScript or Go.
How the two differ
A session proves who someone is. A token proves what a caller may do.
- Human auth
- Sign-in methods in, one server-side session out. The browser holds a cookie. Your app asks theAuth who the user is. Revoke by ending the session.
- AI agent auth
- The agent has an owner and a token with permission patterns, an expiry and an audit row per decision. MCP clients get OAuth 2.1 access tokens bound to one resource. Revoke one agent without touching anyone else.
Track 1
Human auth in about ten lines.
Install, configure one sign-in method, read the signed-in user. Magic links need no password database to start, and passkeys, TOTP, OAuth and SAML add on top.
1 Scaffold a full app, or add the package to your own.
pnpm create @glinr/theauth-appOr add it to an existing project. The SQLite driver is a peer dependency, so install it too:
pnpm add @glinr/theauth sql.jsnpm users: npm create @glinr/theauth-app and npm install @glinr/theauth sql.js.
2 Create the instance and send a sign-in link.
import { createTheAuth } from "@glinr/theauth";
const theauth = await createTheAuth({
database: { provider: "sqlite", url: "app.db" },
baseUrl: "http://localhost:3000",
auth: { session: { secret: process.env.SESSION_SECRET! } }, // 32+ characters
magicLink: {
appUrl: "http://localhost:3000",
sendMagicLink: async (email, _token, url) => {
console.log(`sign-in link for ${email}: ${url}`);
},
},
});
await theauth.magicLink?.sendLink("[email protected]");TypeScript quickstart All sign-in methods Guide: human login in Hono
1 Add the module. Keep the /v2 suffix.
go get github.com/glincker/theauth-go/v2Optional embedded SQLite backend (needs Go 1.26):
go get github.com/glincker/theauth-go/storage/sqlite2 Mount it in your router. Imports: theauth, storage/memory, chi.
a, err := theauth.New(theauth.Config{
Storage: memory.New(),
BaseURL: "http://localhost:8080",
})
if err != nil {
log.Fatal(err)
}
defer a.Close()
r := chi.NewRouter()
a.Mount(r) // /auth/*: magic link, passkeys, TOTP, OAuth, sessions
r.With(a.RequireAuth()).Get("/me", func(w http.ResponseWriter, r *http.Request) {
user, _ := theauth.UserFromContext(r.Context())
w.Write([]byte("hello " + user.Email))
})
log.Fatal(http.ListenAndServe(":8080", r))Track 2
AI agent auth: identities, scoped tokens, MCP.
Give each agent its own owner, permissions and audit trail, or put an OAuth 2.1 authorization server in front of your MCP server so clients you have never met can register and sign in.
1 Install the core. Add the Hono adapter if you want the MCP OAuth endpoints.
pnpm add @glinr/theauth sql.jspnpm add @glinr/theauth-hono hono @hono/node-server2 Create an agent and authorize a call by its token.
import { createTheAuth } from "@glinr/theauth";
const theauth = await createTheAuth({
database: { provider: "sqlite", url: "app.db" },
agents: { enabled: true },
});
const agent = await theauth.agent.create({
ownerId: "user-123", // a row that exists in theauth_users
name: "report-bot",
type: "autonomous",
permissions: [{ resource: "reports:*", actions: ["read"] }],
});
// agent.token is "kv_...", shown once. Store it now.
const result = await theauth.authorizeByToken(agent.token, {
action: "read",
resource: "reports:q3",
});
// result.allowed === true, result.auditId links to the audit row1 The authorization server is in the main module. MCP servers validate tokens with the small resource module.
go get github.com/glincker/theauth-go/v2go get github.com/glincker/theauth-go/mcpresource2 Protect your MCP server's routes with one middleware.
v := mcpresource.New(
"https://mcp.example.com", // your MCP server's resource URI
mcpresource.WithJWKS("https://auth.example.com/oauth/jwks"),
)
r := chi.NewRouter()
r.Use(v.Middleware) // 401 with resource metadata pointers when the token is bad
r.Get("/tools", func(w http.ResponseWriter, r *http.Request) {
p, _ := v.Principal(r.Context())
json.NewEncoder(w).Encode(map[string]any{"subject": p.Subject, "scope": p.Scope})
})Guide: the authorization server too MCP authorization docs theauth-go overview
Before you run two servers
Pick where short-lived state lives
Rate limit counters, device codes and nonces default to process memory. Switch one line when you add instances.
// default, no config
createTheAuth({ /* ... */ })
- Atomic counters: yes.
- Shared across instances: no.
- Lost on restart. Fine for development and one process.
secondaryStorage: "database"
- Atomic counters: yes, a single guarded UPDATE.
- Shared across instances: yes.
- Runs on SQLite, Postgres, MySQL and D1, with no new infrastructure.
secondaryStorage: cloudflareKvStorage(env.AUTH_KV)
- Atomic counters: no. Rate limits are soft.
- Shared: eventually, a write can take up to a minute to show elsewhere.
- Good for plain values such as device codes, if you accept the delay.
secondaryStorage: redisStorage(new Redis(url))
- Atomic counters: yes.
- Shared across instances: yes.
- Works with Redis, Valkey, Upstash and Dragonfly.
defineSecondaryStorage({ get, set, delete, incr })
- Bring your own get, set and delete.
- Atomic counters: only if you supply incr.
- Without it, the helper builds one from get and set, and it is not atomic.
Secondary storage holds rate limit counters, device codes and other short-lived state. See the secondary storage docs for the interface and tradeoffs.
Where to go next
Guides Full quickstart Compare with other auth tools Multi-agent systems Changelog
Get started
Give your first agent an identity.
Install the package, create an agent with scoped permissions, and read its first audit record. The core runs on Postgres, SQLite, MySQL or D1, and the Go module needs a single go get.
npm install @glinr/theauthgo get github.com/glincker/theauth-go/v2