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.
db instance; pass the connection URL and theAuth manages its own tables. See data migration below for how to move existing rows.
Client SDK
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:
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.
Cookie defaults
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 prefixedtheauth_. 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").
- Sessions. A theAuth session row (
theauth_sessions) holds onlyid,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 thelegacyAdapterabove to keep people signed in, or have them sign in again. - Passwords. The
usernamemodule verifies PBKDF2 hashes in the formatpbkdf2:<iterations>:<saltHex>:<hashHex>only. better-auth’scredentialaccount 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.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.
Related
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.