Skip to main content
better-auth is a solid human-auth library. If your product now needs AI agents as first-class entities, an MCP OAuth 2.1 server, GDPR data export tooling, or trust scoring per agent, theAuth is worth the switch. If you rely on an OAuth provider that better-auth covers but theAuth does not ship first-class (we have 17 plus a generic OIDC factory as of 2026-04), you may want to wait.

Concepts map

Server migration

Next.js App Router

theAuth has no emailAndPassword config key. Its built-in password module authenticates by username, see Username and password for the real shape and how to pair it with email verification if you need an email-first flow.

Hono

Database adapter

better-auth supports Prisma, Drizzle, Mongoose, and others. createTheAuth always runs on its own Drizzle layer. @glinr/theauth-prisma lets you query theAuth tables through an existing PrismaClient, but it is a standalone query layer, not a database backend for createTheAuth, see Prisma adapter.
theAuth runs its own schema migrations. You do not pass your Drizzle db instance; pass the connection URL and theAuth manages its own tables. See data migration below for how to move existing rows.

Client SDK

For React, swap the hook import:

OAuth providers

GitHub, Google, and Discord side-by-side:
clientId and clientSecret belong to the createXProvider(...) call. The oauth() plugin itself takes providers as a record of ready-made OAuthProvider instances, and the oauth plugin requires auth.session so it can issue a session on callback. The default callback URL is {baseUrl}/auth/oauth/callback/{provider}, so include your adapter mount path in baseUrl (or pass buildRedirectUri). For a provider without a createXProvider function, use the generic OIDC factory:

Breaking differences

Session tokens

better-auth and theAuth use different token structures. An existing session token from better-auth will not be accepted by theAuth and vice versa. auth.adapter only accepts a single adapter, there is no built-in multi-adapter “accept both” mode, so bridge the transition window yourself with customAuth, which wraps a function that reads the old better-auth cookie:
You can configure both. For the endpoints that theAuth plugins register, the user is resolved by trying legacyAdapter first and then falling back to a theAuth session (auth.session) cookie. Note that theauth.auth.resolveUser(request) consults only the adapter, so in your own server code check theauth.auth.session too if you need to accept both. Once traffic drops to near-zero on the old cookie, drop the adapter and keep auth.session only. Secure is not one global setting. The OAuth callback sets it when baseUrl starts with https://. The standalone cookie session manager defaults it to on only when NODE_ENV is production, and you can override it with cookieOptions.secure. If your better-auth app set secure: false in a staging environment, check your baseUrl and NODE_ENV there.

@better-auth/agent-auth

If you use @better-auth/agent-auth, none of its config maps 1:1. That package is a thin wrapper; theAuth replaces it with a native AgentIdentity entity, built-in delegation, ephemeral sessions, and the MCP OAuth server. Start with the agents quickstart rather than trying to adapt your existing agent-auth config.

Data migration

theAuth keeps its own tables, all prefixed theauth_. Run createTheAuth once so it creates them, then copy rows across. Users go into theauth_users and provider links into theauth_oauth_accounts. Adjust the source column names to your better-auth schema (Postgres setups often use camelCase such as "emailVerified" and "createdAt").
Column names in better-auth can vary depending on your adapter and any custom fields you added. Run SELECT column_name FROM information_schema.columns WHERE table_name = 'user' against your database to confirm the exact names before running the migration.
Two things do not migrate:
  • Sessions. A theAuth session row (theauth_sessions) holds only id, user_id, expires_at, and metadata. The token is a signed JWT that references that row, so better-auth session tokens cannot be copied across. Use the legacyAdapter above to keep people signed in, or have them sign in again.
  • Passwords. The username module verifies PBKDF2 hashes in the format pbkdf2:<iterations>:<saltHex>:<hashHex> only. better-auth’s credential account hashes are not in that format and will not verify. Follow the forced reset or lazy rehash approach in Migrate from Auth0, which applies the same way here.

Rollback

Keep better-auth running behind a feature flag while you roll out theAuth to a percentage of traffic.
Set THEAUTH_ROLLOUT=10 to start at 10%, then raise it over days as you validate sessions in the theAuth tables. The customAuth-based legacyAdapter described above keeps existing users resolvable during the overlap.

FAQ

Does theAuth support all the OAuth providers better-auth has? No. We ship 48 OAuth providers: 22 first-class (Apple, Atlassian, Discord, Dropbox, Figma, GitHub, GitLab, Google, Kakao, Kick, Linear, LinkedIn, Microsoft, Notion, PayPal, Reddit, Slack, Spotify, Twitch, Twitter/X, Vercel, Zoom) and 26 legacy presets (for example Auth0, Keycloak, Okta and Cognito). Any provider with a standard OAuth 2.0 authorization code flow works via the generic provider factory, but you write the config by hand. If a specific provider matters to you, open an issue. Is Prisma supported? Partly. createTheAuth itself takes database: { provider, url } and runs on Drizzle. @glinr/theauth-prisma gives you createPrismaAdapter(prisma) to read and write theAuth tables from code that already uses Prisma, it does not replace the core instance. See the Prisma adapter docs. Do I need to install an MCP plugin? No separate package. Build the OAuth server with createMcpModule from @glinr/theauth/mcp and pass it to your adapter as the mcp option, see MCP. The mcp key on createTheAuth only creates the MCP tables. Can I run better-auth and theAuth side by side? Yes. Use customAuth to wrap your existing better-auth instance’s session check as a legacyAdapter, and route traffic with a feature flag as shown above. Will my users have to sign in again? With the legacyAdapter, not right away: theAuth plugin endpoints keep resolving the better-auth session. The adapter does not mint theAuth sessions, so users move onto theAuth sessions when they next sign in through theAuth. Without the adapter, yes, existing tokens will be rejected.

theAuth vs better-auth

Feature-by-feature comparison before committing to a migration.

Database setup

Configure the Drizzle-based database layer theAuth uses.

Prisma adapter

Query theAuth tables from an existing PrismaClient.

Agent identity

The agent primitives that motivated the switch from better-auth.
Last modified on October 18, 2026