FAQ: production readiness, why a new library, OAuth, MCP, framework support

[thegdsks]

FAQ: production readiness, OAuth, MCP, framework support

Running FAQ for theauth-go. The goal is to answer the "should I use this?" questions honestly so you don't have to read commit history. Last refreshed at v2.5.0.

Is it production-ready?

Yes, for v1.0+ surfaces: session auth (magic link, email/password), OAuth providers, RBAC, and the audit log are covered by STABILITY.md's SemVer contract. v2.0's OAuth 2.1 authorization server, MCP resource-server authorization, and agent-identity primitives (delegation chains, RFC 8693 token exchange) are feature-complete as of v2.0.0 and in production use by early adopters.

What's shipped, in order: magic link + email/password (v0.2), OAuth providers via a Provider interface (v0.3-v1.0, now 12 providers: GitHub, Google, Microsoft, Discord, Facebook, Slack, GitLab, Bitbucket, Twitch, LinkedIn, X/Twitter, Apple), TOTP 2FA (v0.4), WebAuthn/passkeys (v0.5), OAuth 2.1 authorization server + MCP authorization + agent identity + delegation (v2.0), organization multi-tenancy + RBAC + SCIM + SAML (v2.0-v2.4), Config.LifecycleHooks (v2.5).

See CHANGELOG.md for the current release and exactly what landed in each version.

Why a new library? Why not Auth0 or Clerk?

Auth0 and Clerk are well-built SaaS products. The reasons people often look for an alternative:

• Per-MAU pricing. Both bill by monthly active users. Past the free tier, the line gets steep, especially for B2C apps with millions of low-revenue users.
• Data residency. Your users' email addresses, hashes, and session activity live in the vendor's database. For some companies (EU public sector, healthcare, regulated fintech) this is a hard no.
• Lock-in. Migrating off a hosted auth provider is famously painful. Owning the schema from day one avoids that.
• Library vs service ergonomics. Some teams want auth to be a Go package they go get and embed, not an external API they call.
• MCP authorization. theauth-go ships RFC 9728 MCP resource-server metadata and CIMD out of the box; none of Auth0, Clerk, or better-auth do today.

If none of those apply, Auth0, Clerk, and Stytch are great. If any do, theauth-go is one of the options to consider, alongside Ory Kratos and rolling your own.

Why not Ory Kratos?

Ory Kratos is excellent. The trade is library vs service.

Kratos is a deployable identity service. You run it as a separate process. It has its own Postgres. You talk to it over HTTP from your app. Polished admin API, mature, big OSS user base.

theauth-go is a Go library you import. No extra process. No extra Postgres (it uses your Postgres or MySQL pool). Smaller surface area, less operational overhead, but also less out of the box (no admin UI, no webhook flow customization beyond Config.LifecycleHooks).

If "I'm going to deploy another service alongside my app and operate it" is fine, Kratos is a strong choice. If "I just want go get and a.Mount(r)" sounds better, this library is for you.

What is MCP OAuth 2.1? Why do you keep mentioning it?

MCP is the Model Context Protocol, Anthropic's spec for connecting LLMs to tools and data sources. MCP servers need OAuth 2.1 with PKCE S256, plus the RFC stack: 9728 (protected resource metadata), 8707 (resource indicators), 8414 (server metadata discovery), 7591 (dynamic client registration). Implementing that yourself is several weeks of careful work plus ongoing spec drift.

theauth-go ships an MCP-compliant authorization server today: RFC 9728 /.well-known/oauth-protected-resource, Client ID Metadata Documents (CIMD) per the MCP spec, agent identities with revocable delegation chains, and RFC 8693 token exchange with actor-chain capping. The companion mcpresource module (github.com/glincker/theauth-go/mcpresource) is a zero-dependency SDK for building MCP resource servers against it.

The sibling TS project theauth ships the same MCP-authorization story.

Can I use net/http instead of chi?

Mostly yes, but chi is the first-class router today. a.Mount(r) takes a chi router because chi gives us nice route grouping and middleware composition. Under the hood the handlers are plain http.Handlers. See the examples/stdlib-app example for a working net/http-only integration, and examples/gin-app / examples/echo-app for those frameworks.

How do I migrate from better-auth, Auth0, or Cognito?

For better-auth (TypeScript): if you're moving a Node service to Go, the cleanest path is not "migrate auth at the same time as migrating languages" - that doubles your risk surface. Either keep the TS service and call it from Go, or, for a fresh Go service, adopt theauth-go directly and rehash passwords on next signin (better-auth uses scrypt by default; theauth-go uses Argon2id).

For Auth0 or AWS Cognito, see the dedicated migration guides: MIGRATING-FROM-AUTH0.md and MIGRATING-FROM-COGNITO.md, plus the cmd/theauth-migrate CLI tool that ships in this repo.

How does session storage work?

Opaque session tokens, stored server-side. The client gets an httpOnly secure cookie containing a random token. The server looks it up on every request.

• No JWTs for sessions. Sessions can be revoked instantly (sign out, password reset, ban) by deleting the row. (JWTs are used for the separate OAuth 2.1 authorization server surface, where short-lived, audience-bound, Ed25519-signed access tokens are the standard.)
• Postgres backend uses pgx plus sqlc-generated queries, lives in your existing Postgres pool. MySQL backend added at v2.4. In-memory backend for tests and demos.

To add a custom backend (Redis, DynamoDB, SQLite, etc.), implement the Storage interface and run the public storagetest contract suite against it.

What email sender does it use?

email.Noop by default, logs the link to stdout for local dev. For production, implement the email.Sender interface and plug in Resend, Postmark, SES, SendGrid, etc.

Is there a hosted version?

No. theauth-go is and will remain a library you embed. If you want a hosted product, that's a separate, non-Go product line - not this repo.

How big is the dependency footprint?

Small and deliberate. Direct runtime dependencies today: github.com/jackc/pgx/v5 (Postgres), github.com/go-sql-driver/mysql (MySQL), github.com/go-chi/chi/v5 (router), golang.org/x/crypto (Argon2id, Ed25519), golang.org/x/time (rate limiting), github.com/go-webauthn/webauthn (WebAuthn/passkeys), github.com/pquerna/otp (TOTP), github.com/crewjam/saml + github.com/russellhaering/goxmldsig + github.com/beevik/etree (SAML), github.com/oklog/ulid/v2 (IDs). Postgres and MySQL drivers only matter if you use those backends; the in-memory backend has none of that.

How do I report a security issue?

Email [email protected], or use GitHub Security Advisories. Please don't open a public issue for vulnerabilities. See SECURITY.md for supported versions and SLA targets.

What's the relationship between theauth-go and the TS sibling theauth?

Two separate libraries, one team, one design philosophy, a deliberately shared shape so the mental model carries between them. Both treat AI agents as first-class identities, both ship MCP OAuth 2.1 compliance, both prefer opaque sessions over JWTs for the traditional auth surface, both use Argon2id with OWASP-recommended defaults. The Go library doesn't depend on the TS one; they share design, not code.

Does it work with gRPC?

The chi middleware is HTTP-specific. For gRPC services, validate sessions at your gateway (the HTTP service that proxies into your gRPC mesh) and pass the user ID into your gRPC interceptors. Open an issue if a native interceptor would help you.

What about CORS?

theauth-go doesn't ship CORS middleware. Standard chi CORS middleware (e.g. cors.AllowAll()) composes cleanly with a.Mount(r).

Anything else?

Ask in this discussion or open a GitHub issue.

Repo: https://github.com/glincker/theauth-go
Sibling TS: https://github.com/glincker/theauth
Docs: https://theauth.dev

Appendix: how to contribute

• Real-world feedback. If you ship theauth-go and find an error code shape that's awkward, a missing field, or a default that's wrong for your case, open an issue.
• Storage backend implementations. Postgres, MySQL, and in-memory are first-class. The Storage interface is small and documented; the storagetest package gives you a contract suite to verify a new backend against. PRs welcome.
• Documentation gaps. If something in the README or docs site is unclear or wrong, that's a doc bug worth fixing.

See CONTRIBUTING.md for the development setup and test conventions.

Appendix: where to follow updates

• GitHub releases: https://github.com/glincker/theauth-go/releases
• Changelog: https://github.com/glincker/theauth-go/blob/main/CHANGELOG.md
• Discussions: this page
• Sibling project (TS): https://github.com/glincker/theauth