{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/clerk-migration", "result": {"data":{"markdownRemark":{"html":"

Migrating authentication systems represents a critical infrastructure decision that affects every user interaction with your application.\nClerk provides a robust authentication platform, but developers increasingly seek alternatives offering greater control, cost predictability, or self-hosting capabilities. SuperTokens delivers these advantages while maintaining enterprise-grade security and a\ncomprehensive feature set.

\n

This guide provides a detailed roadmap for migrating from Clerk to SuperTokens, covering migration strategies, user data export and import procedures, session handling, multi-factor authentication (MFA) preservation, and rollout best practices.

\n

Migration Strategies: Choosing Your Approach

\n

The selection of a migration strategy depends on the size of the user base, the acceptable downtime, and operational constraints. SuperTokens supports multiple migration patterns, each with distinct trade-offs.

\n

What Migration Options Exist?

\n\n

Users migrate individually upon their next login attempt. The system checks the Clerk first, validates credentials, imports the user into SuperTokens, and issues a new session. This approach requires maintaining both systems temporarily, but it distributes the migration load over time and targets active users first.

\n\n

Export all users from Clerk and import them into SuperTokens in batches by using the /bulk-import/users API. This method migrates users upfront, enabling faster Clerk deprecation.

\n\n

Automated scripts extract users from Clerk, transform data into the SuperTokens format, and execute imports. This approach offers maximum control for complex migration requirements.

\n\n

Combine bulk import for the majority of users with lazy migration for edge cases or recently registered accounts.

\n

1. Trickle Migration (Lazy Migration)

\n

Trickle migration enables seamless, incremental user transitions without bulk data operations. This approach mirrors Clerk’s own migration recommendations for minimal disruption.

\n

How It Works:

\n
    \n
  1. User attempts to log in with email and password.
    2. \n
  2. Check if the user exists in SuperTokens.
    3. \n
  3. If not found, authenticate against Clerk.
    4. \n
  4. Upon successful Clerk authentication, import the user into SuperTokens.
    5. \n
  5. Issue SuperTokens session token.
    6. \n
  6. Subsequent logins authenticate directly against SuperTokens.
    7. \n
\n

Advantages:

\n\n

Considerations:

\n\n

2. Bulk Import

\n

Bulk import migrates all users upfront through SuperTokens’ /bulk-import/users endpoint, enabling rapid Clerk deprecation.

\n

Key Steps:

\n
    \n
  1. Export the complete user dataset from the Clerk dashboard.
    2. \n
  2. Transform data into SuperTokens bulk import format.
    3. \n
  3. Submit batches (up to 10,000 users per request).
    4. \n
  4. Monitor import job status.
    5. \n
  5. Handle failures and retry as needed.
    6. \n
\n

Advantages:

\n\n

Considerations:

\n\n

3. Full Migration via Scripts

\n

Scripted migration provides maximum flexibility for complex requirements, inspired by Better Auth’s migration guides.

\n

When to Use:

\n\n

Script Responsibilities:

\n\n

Exporting and Importing Clerk Users

\n

Successful migration depends on accurately exporting Clerk user data and transforming it into a SuperTokens-compatible format.

\n

Export Users from Clerk Dashboard

\n

Steps:

\n
    \n
  1. Navigate to Clerk Dashboard → Configure section → settings.
    2. \n
  2. Click Export Users.
    3. \n
  3. Download an export file.
    4. \n
\n

\n \n