- 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.
- 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’sclerkMiddleware 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.
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.
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: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 namedtheauth_users, theauth_oauth_accounts, and theauth_username_accounts, and createTheAuth creates them for you.
Next sign-in rehash
Import each password user with a placeholder row intheauth_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:
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:
- Hard cutover. All signed-in users sign in once on the theAuth flow. Simpler. Set an expectation with a banner for a few days.
- 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.
Rollback
Keep Clerk wired up on a different subdomain while you roll out.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. Theorganization 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
additionalFieldsmodule (createAdditionalFieldsModule) can define and validate a date-of-birth field. Enforce the rule in your own sign-up handler. - Impersonation with TTL: the
adminconfig oncreateTheAuthenablestheauth.admin.impersonate(adminUserId, targetUserId), withimpersonationTtlSecondsto set the lifetime.
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.
Related
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.