Migrate from Auth0

Move Auth0 sessions, the auth route handler and the Management API onto MainSDK auth, with a guided user move and a rollback.

Planned for 0.7

Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.

Stability The promise an interface ships with.

Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
Beta Usable in production; may change before it becomes stable.
Experimental May change or go away; needs an explicit opt-in in main.yaml.

Stability levels

View as Markdown Open in Claude Edit

Updated 2026-10-28

Move Auth0 sessions, the auth route handler and the Management API onto MainSDK auth, with a guided user move and a rollback. Your Auth0 account stays; nothing here deletes it.

Before you start:

A git repository with a clean working tree. mainsdk migrate works on a branch and never touches yours.
Node 22 and npx mainsdk. No main.yaml yet? migrate writes one; or start with Adopt an existing app.
Your Auth0 keys stay where they are. Move them to secret: references when the driver is chosen (see Secrets).

1. Read the report

text

npx mainsdk migrate auth0 --report-only

The report writes no file. It sorts every Auth0 call in your code into three lists: mapped (an interface call replaces it), raw (it stays behind raw(), with the reason) and needs a person (a policy, a rule file or a call with no interface). Add --json for a machine-readable report.

For the sample app of this guide (packages/cli/test/fixtures/migrate/auth0), the report finds 3 mapped, 0 raw and 1 for a person.

2. What the codemod changes

Where	Before	After
`app/api/auth/[auth0]/route.ts:3`	`export const GET = handleAuth()`	`auth.handlers()`
`app/api/me/route.ts:4`	`const session = await getSession()`	`auth.require(req)`
`lib/users.ts:9`	`export const allUsers = () => management.users.getAll()`	`auth.users.list()`

Each rewrite is mechanical and one line at a time. Imports of Auth0 go when no call needs them, and mainsdk is added to package.json.

3. What stays behind raw()

Nothing in the sample stays behind raw().

A call behind raw() keeps working through the Auth0 host on your network allow list, and mainsdk check still sees it. Each one has a marker comment, // mainsdk migrate: ..., so you can find it later.

4. What needs a person

lib/users.ts:4: no interface call for auth0.com; a person decides

The codemod leaves these lines alone and marks them. No tool should guess a policy.

5. Stateful moves are guided jobs

Data does not move with the code. Each stateful move is a job with steps and a rollback, listed in the pull request and never run by the codemod.

users: Move Auth0 users

Run the Auth0 bulk user export (Dashboard, Extensions, User Import / Export).
Password hashes come only through an Auth0 support request; without them users reset on first sign-in.
Import on staging, compare counts, then switch sign-in for 1%, then all.

Rollback: Keep auth.driver: auth0 until the new driver has served a week.

6. Open the pull request

text

npx mainsdk migrate auth0

This records your sign-in and checkout flows as locked flows first, then creates the branch migrate/auth0, applies the codemods, adds .github/workflows/mainsdk-migrate.yml, runs mainsdk check and the locked flows, commits, pushes and opens one pull request with gh. If a gate fails, the branch is kept and no pull request opens (MAIN-MIGRATE-0001). --no-pr stops after the commit.

Locked flows run again in CI: npx mainsdk migrate flows.

Where you end

You end at the reference architecture mainsdk/saas-web: the same shape, with its tests, benchmark and chaos drills.

text

npx mainsdk init --template mainsdk/saas-web

Was this page helpful?