Skip to main content
Clerk is a hosted identity service with a strong Next.js story and paid tiers that scale with MAU. theAuth is open source, self-hosted, and treats AI agents as a first-class entity next to users. The two trade-offs are real: you give up Clerk’s hosted sign-in UI and org management console, you take back your data, your cookie domain, your rate limits, and your bill. Read this before you cut over. When the switch makes sense:
  • You are hitting Clerk’s MAU pricing tiers and the cost stops matching the value.
  • Your product now needs AI agents as first-class entities, an MCP OAuth 2.1 server, or per-agent trust scoring. Check Clerk’s own agent features first, see theAuth vs paid platforms.
  • You want full control over session cookies, token issuance, and audit logs.
  • Data-handling needs (GDPR export tooling, self-hosted data residency) are easier with a service you run yourself. theAuth supplies building blocks, it does not certify your deployment.
When to wait:
  • You rely heavily on Clerk’s hosted sign-in / sign-up components and have no designer bandwidth to rebuild them. theAuth ships headless building blocks, not a dashboard you drop in.
  • You use Clerk’s B2B Organizations extensively with their admin UI. theAuth has an organization plugin but no hosted admin console yet.
  • You need Clerk-specific features like device attestation at the sign-in edge or their waitlist product.

Concepts map

Server setup

Next.js App Router route handler

Clerk hides its route handling behind the middleware. theAuth exposes an explicit handler so you can see and control what runs.

middleware.ts

Clerk’s clerkMiddleware does three things: verifies the session cookie, attaches auth to the request, and optionally protects routes. theAuth does not ship an equivalent wrapper. Next.js middleware runs on the Edge runtime by default, where you cannot open a Postgres connection to validate a session. So keep middleware to a cheap cookie presence check, and validate the session in server code (pages, route handlers, server actions).
session.validate(token) returns a Session or null, it does not throw. The username module methods (signIn, signUp) throw an Error on failure instead of returning a result object.

Client SDK

Hooks

Sign-in and sign-up pages

Clerk ships <SignIn /> and <SignUp /> components that render their hosted flow inside your layout. theAuth gives you hooks and expects you to build the form.
The useSignIn hook POSTs { email, password } to ${basePath}/auth/sign-in, and useSignUp POSTs to ${basePath}/auth/sign-up. The TypeScript core and adapters do not register those two routes. The username module serves /auth/username/sign-in and /auth/username/sign-up with { username, password } instead, and you have to call theauth.username.handleRequest(request) from your own route handler. Until you add a route that answers the paths the hook calls, build the form against the username endpoints (or theauth.username.signIn in a server action).
If you were relying on Clerk’s first-party passkey UI or phone OTP UI, you will rebuild the forms. useSignIn only handles email and password. Passkeys and phone OTP are server modules with their own endpoints, see the pages under Auth (for example passkey and phone).

Organizations

Clerk’s Organizations model ports cleanly. theauth.org uses the same three concepts: organization, membership, role. It exists only when you pass org: {...} to createTheAuth (it is null otherwise). Built-in roles are owner, admin, member, and viewer.
Clerk’s org:admin, org:member role prefix becomes plain role strings in theAuth. If you have code reading orgMembership.role, search for org: and strip the prefix.

OAuth providers

Clerk configures OAuth providers in its dashboard. theAuth does it in code. Side by side for GitHub and Google:
Update each OAuth app in the provider’s console: change the callback URL from https://<your-clerk>.clerk.accounts.dev/v1/oauth_callback/<provider> to {baseUrl}/auth/oauth/callback/<provider>. With the config above and the adapter mounted at /api/auth, that is https://app.example.com/api/auth/auth/oauth/callback/github. If you want a different URL, pass buildRedirectUri to oauth(). Do this before cutover so the first sign-in after the switch works.

Data migration

Clerk’s data lives in Clerk’s cloud. You export it, then import it. Clerk exposes a Backend API and an SDK. Pagination caps at 500 per page.

Step 1: export users from Clerk

Step 2: import into the theAuth tables

theAuth uses PBKDF2-SHA256 for password hashing. Clerk uses bcrypt. The hashes are not compatible, so password sign-in will not work for imported users until they go through a password reset or a rehash that you write yourself (see next sign-in rehash below). OAuth sign-ins work once the provider is configured. theAuth’s tables are named theauth_users, theauth_oauth_accounts, and theauth_username_accounts, and createTheAuth creates them for you.
Clerk exports historical metadata, not live OAuth tokens. Users will re-authorise the provider the first time they sign in after migration; the refresh token will be fetched fresh. If you rely on the access token for third-party API calls, plan for a grace period where those calls fail until users sign in.

Next sign-in rehash

theAuth’s username module has no legacy-hash bridging hook, verifyLegacyHash and similar options do not exist, and there is no API to set a password hash for an existing user. theauth.username.signUp always creates a brand new user row, so calling it for an imported user would create a duplicate account. If you want password sign-in to keep working without a forced reset, you have to check the Clerk hash yourself in front of theAuth and write a PBKDF2 hash into theauth_username_accounts yourself.
Import each password user with a placeholder row in theauth_username_accounts (any value that is not in pbkdf2:<iterations>:<saltHex>:<hashHex> form never verifies), set theauth_users.force_password_reset, and keep Clerk’s bcrypt hash in your own legacy_password_hashes table. Migrate from Auth0 shows that import script. Then verify the legacy hash in your own sign-in handler:
After 30 to 60 days, drop the legacy_password_hashes table and force a password reset (the passwordReset module) for any stragglers.

Session cookies

Clerk sets the __session cookie signed by Clerk’s keys. theAuth cannot read those cookies without calling Clerk. That means one of two things:
  1. Hard cutover. All signed-in users sign in once on the theAuth flow. Simpler. Set an expectation with a banner for a few days.
  2. Side-by-side with a rollout flag. Keep Clerk running for a percentage of traffic while theAuth takes the rest. Each user picks one stack until you flip them to 100% theAuth. Sample middleware below.
Unlike a library-to-library migration, there is no cookie adapter that verifies Clerk tokens locally. Clerk session tokens require round-trips to Clerk’s backend.

Rollback

Keep Clerk wired up on a different subdomain while you roll out.
Start at THEAUTH_ROLLOUT=10, watch error rates and sign-in conversions, raise to 100 over a week or two. Cut the Clerk app once traffic is zero.

FAQ

Will my users be signed out on cutover day? Yes, unless you run a side-by-side rollout. Clerk session cookies cannot be verified without Clerk, so theAuth cannot accept them. A one-time sign-in is the simplest story. Tell users ahead of time and keep the old subdomain alive as a fallback. Do OAuth tokens survive the migration? No. Clerk does not export live OAuth access or refresh tokens. Users re-authorise the provider on first sign-in after migration. If your app calls provider APIs using those tokens, plan for a grace period. Does theAuth have an equivalent of Clerk’s Organizations UI? Not hosted. The organization plugin has the same model (organization, membership, role). You build the UI. The example app has a minimal organization page to copy. What about Clerk’s waitlist, age gate, or impersonation features?
  • Waitlist: not in theAuth core. Gate sign-up in your own route handler.
  • Age gate: the additionalFields module (createAdditionalFieldsModule) can define and validate a date-of-birth field. Enforce the rule in your own sign-up handler.
  • Impersonation with TTL: the admin config on createTheAuth enables theauth.admin.impersonate(adminUserId, targetUserId), with impersonationTtlSeconds to set the lifetime.
Will my Clerk webhooks still fire? No. Clerk webhooks are driven by Clerk’s internal events. theAuth can send signed webhooks and stream events from your own process, see Webhooks and event streaming. If you used Clerk webhooks to sync users to Stripe, port that to a webhook consumer or a call in your own sign-up handler. I use Clerk’s JWT templates. What replaces them? The JWT session module (createJwtSessionModule) takes a customClaims callback that runs at token issuance. It receives { id, email, name } for the user and returns any extra claims you want in the access token. See JWT sessions. Can I keep Clerk for B2B and use theAuth for B2C in the same app? Technically yes, but you will spend more time on the boundary than on the migration itself. Pick one.

theAuth vs paid platforms

Structural comparison of theAuth versus Clerk and Auth0.

Migrate from better-auth

Migration guide if you are coming from better-auth instead.

GDPR tooling

Data export and deletion helpers that self-hosting makes straightforward.

Agent identity

The agent layer Clerk does not model natively.
Last modified on November 1, 2026