Migrate from Clerk to ZITADEL: what the move involves
Moving a Clerk application to self-hosted ZITADEL is feasible, but the move hinges on two things: getting password hashes out of Clerk so users keep their passwords, and rebuilding the sign-in, sign-up and account screens that Clerk supplied as prebuilt components. If your renewal, per-user pricing, data residency requirement or lock-in concern is the reason you are looking, plan for the export and the front-end rewrite first, because those decide the schedule. The work is usually done by platform or security engineers who own the identity configuration and the deployment, with front-end engineers rebuilding the login screens against ZITADEL's hosted login. Clerk's prebuilt components are typically the largest rework item, since every page that embedded them needs a replacement flow, and the session handling in your back end has to change with it.
Start by confirming what Clerk's export gives you. The dashboard export is a CSV of users, and password hashes are only included where your Clerk plan and export permissions allow it, so check this with Clerk before you commit to a date. Next, decide how each Clerk organization maps to ZITADEL's structure of instances, organizations and projects, and list every enterprise connection your customers use, since each one must be recreated as an identity provider on the ZITADEL side. Then import a test batch with ZITADEL's ImportHumanUser endpoint or the admin ImportData bulk endpoint, both of which accept a hashed password with an algorithm, and confirm that a test user can sign in with the existing password. ZITADEL validates the imported password on first login and then rehashes it with its configured hasher, so the password does not need to be reset in the common case, but you should verify this against your own hash algorithm before relying on it.
Risk concentrates in three places: users whose hashes cannot be exported, customers whose SSO configuration is undocumented, and applications that depend on Clerk session tokens or webhooks. Plan a fallback for the first group, such as a password reset or a just-in-time migration path that ZITADEL's migration guides describe. Keep a parallel run for a small set of internal accounts and one customer organization before switching the rest, and keep Clerk active until your monitoring shows no sign-in failures. Ask for a written scope that lists each component, the migration checks and the cutover criteria before work starts, so the effort is visible to finance and security alike.
Which Clerk capabilities map to ZITADEL and which need rework
This table maps each Clerk capability to its nearest ZITADEL equivalent and marks it as clean, needs rework or gap. Read the status column first, then the notes, which name what to check in Clerk's own documentation and in a test instance before you commit to a cutover date. Items marked gap need a design decision in your application, not only a configuration change.
| Clerk capability | ZITADEL equivalent | Status and what to check |
|---|---|---|
| User records and profiles | Human users imported through ImportHumanUser or the admin ImportData endpoint | Clean for core fields like email and name. Map any custom attributes before import. |
| Hashed passwords | hashedPassword import with algorithm and value, bcrypt in documented examples | Needs rework. Confirm Clerk's hash algorithm is one ZITADEL can verify before exporting. |
| Organizations and memberships | Organizations inside an instance, with projects and grants for roles | Needs rework. Rebuild membership and role assignments as ZITADEL grants per project. |
| Enterprise SSO connections | Per-organization federation over SAML 2.0 or OIDC, plus SCIM 2.0 provisioning | Needs rework. Recreate each customer connection and confirm the customer's IdP settings. |
| Social login | Federation with Google, GitHub, GitLab, Apple, Entra ID and Okta over OIDC or SAML | Needs rework. Register new redirect URIs and client credentials with each provider. |
| Passkeys and MFA | Passkeys based on FIDO2 and WebAuthn, with password fallback | Needs rework. Confirm with Clerk's docs whether enrolled factors export; expect users may re-enroll. |
| Sessions and token lifetimes | OIDC sessions and tokens issued by the ZITADEL login flow | Needs rework. Confirm session and token lifetimes in ZITADEL docs and align your app's session handling. |
| Webhooks and user events | No direct equivalent in the documented features reviewed here | Gap. Confirm ZITADEL's event options, or plan a SCIM or custom consumer to replace Clerk webhooks. |
The migration sequence from inventory to decommission
This sequence moves a Clerk application to self-hosted ZITADEL in controlled stages, so each stage produces evidence that the next one can rely on. Users keep their passwords, organizations and enterprise connections are mapped deliberately, and Clerk is switched off only after the cutover has been verified.
Inventory users, organizations and connections
Your team lists everything Clerk currently holds: the user export with password hashes, organizations and memberships, roles and metadata, enterprise SAML or OIDC connections, social providers, MFA enrollments, and the redirect URLs and API keys your applications use. The Clerk export is a CSV with hashed passwords, so restrict who can open it and confirm which fields you need from the API. The output is an inventory sheet that maps each Clerk object to a planned ZITADEL object (instance, organization, project, identity provider or user), with an owner for each open question.
Build a pilot on a test instance
Stand up a non-production ZITADEL instance on your own infrastructure, using the self-hosting path your platform team has chosen and PostgreSQL in a supported version. Import a small, representative set of users, including accounts with different hash types if your export contains them, and connect one test application through OpenID Connect. Confirm that the hosted login, password reset and MFA flows work for these users. The output is a pilot record listing which users logged in with their original password and which failed, with the reason for each failure.
Import users with password hashes
Load the full user set through the ImportHumanUser endpoint or the admin ImportData bulk endpoint, each of which accepts a hashed password with its algorithm. Map Clerk user fields to ZITADEL profile fields and record every record that was rejected. Because the documented examples use bcrypt, confirm that your Clerk export hashes are compatible with a verifier ZITADEL supports before you import at scale. The output is a verified import report with counts of created, skipped and failed users, and a reconciliation against the source export.
Run a parallel period with just-in-time checks
Keep Clerk live while ZITADEL serves a limited group of applications or users. On a migrated user's first login, ZITADEL validates the imported password with the matching verifier and then rehashes it with the configured hasher, so you can watch that transition happen for real accounts. Track login success, lockouts, MFA enrollment and any users who must reset their password. Build the organization structure and enterprise identity provider connections in parallel, one customer at a time. The output is a parallel-run log and a signed-off list of organizations and connections that behave correctly.
Prepare a rollback plan before cutover
Write down the exact steps to return traffic to Clerk, including DNS or application configuration changes, the Clerk instance and keys that must remain active, and the point after which new ZITADEL-only data (such as password changes or new users) would be lost or need to be reconciled. Agree who can trigger the rollback and how the team will know it is needed. The output is a rollback runbook that the security and application owners have reviewed and accepted.
Cut over applications to ZITADEL
Switch each application's identity configuration to ZITADEL in the order agreed in the pilot, replacing Clerk's prebuilt components with the hosted login and updating the sign-in, sign-up and account screens. Verify token issuance, session handling, logout and role claims against the project and grant model you designed. Monitor authentication errors and support tickets during the window. The output is a cutover checklist per application, signed off with the test results attached.
Decommission Clerk after verification
Once every application has run on ZITADEL for an agreed observation period, archive the Clerk export and API logs your audit or records policy requires, revoke Clerk API keys and webhooks, remove Clerk DNS records and SDK code, and cancel the subscription after confirming the final billing date with Clerk. Keep the rollback runbook and import report on file for your compliance evidence. The output is a decommission record confirming that no application still calls Clerk and that the retained data sits where your policy says it should.
Exporting users with hashed passwords from Clerk
The export is the first step of the move, and its scope decides what ZITADEL can import without forcing password resets. The cards below cover the dashboard export, the API pulls that complete it, and the integrations that must be rebuilt on the new identity provider.
Dashboard user export
Clerk's dashboard can export the user list as a CSV. Before you rely on it, confirm with Clerk whether that file includes the password hash and its algorithm for your instance, because ZITADEL needs both to validate existing passwords on a user's first login. Export a small test set, open the file, and check that each row carries a hash value and an algorithm column. If either is missing, the rest of the migration plan changes.
Hash algorithm and verifier match
ZITADEL's documented import examples use bcrypt, and it validates an imported password with the matching verifier before rehashing it with its own configured hasher. Record the algorithm Clerk reports for each hash and compare it with the verifiers ZITADEL supports for your version. Any user whose hash uses an unsupported algorithm will need a password reset or a just-in-time approach, so flag those accounts before cutover.
Organizations and memberships through the API
The CSV covers users, not the B2B structure around them. Pull organizations, memberships and roles through Clerk's Backend API so you can map each Clerk organization to a ZITADEL organization and project. Ask Clerk to confirm which fields the API returns for your plan, and store the raw responses as evidence of what was exported.
User metadata and public attributes
Custom public and private metadata often holds roles, plan tiers or onboarding flags that the application reads. Export these fields through the API for every user, since the dashboard file may omit them. Decide which values become ZITADEL user metadata or project grants, and which are removed because they duplicate data held elsewhere.
Frontend SDK and session verification
Clerk's frontend SDK and its backend session verification sit in your application code, so each one must be replaced by an OpenID Connect client that talks to ZITADEL. List every route that reads a Clerk session, every middleware that verifies tokens, and every call to the Clerk SDK. Plan the replacement token validation against ZITADEL's issuer and keys, and test it on a staging copy before any user is moved.
Webhooks, social credentials and session expiry
Clerk webhooks that sync user events into your database must be inventoried and replaced. Social provider credentials, such as Google or GitHub client IDs and secrets, belong to your own developer accounts, but they must be re-registered with ZITADEL's redirect URIs before users can sign in. Confirm with Clerk what happens to active sessions at cutover, since users may need to sign in again.
How users keep their passwords after the switch
ZITADEL can keep existing passwords working because its ImportHumanUser management endpoint and the admin ImportData bulk endpoint both accept a hashedPassword object with a value and an algorithm field. The documented examples use bcrypt, so the first decision is whether the hashes in your Clerk export use an algorithm ZITADEL can verify. Clerk's export gives you the stored hash and its format, and you should confirm with Clerk support and against ZITADEL's migration guide which algorithms the import accepts before you write any import script. If the algorithm is not on that list, users cannot be moved with their passwords intact, and you will need to plan a password reset flow or a different migration path.
On a migrated user's first login, ZITADEL checks the password against the imported hash using the matching verifier. If the password is correct, ZITADEL rehashes it with its own configured hasher and stores the new hash, so the imported value is replaced over time as users sign in. Users who never log in again keep their old hash, which is one reason to decide early how long the Clerk export file is kept and where it is stored, since it contains credential material. Treat that file as sensitive, restrict access to it, and delete it once the import is verified.
Test this with sample accounts before any production import. Create a set of test users in Clerk that cover each password hash type you find in the export, including accounts with no password and accounts using social login only. Import them into a non-production ZITADEL instance, log in with each known password, and confirm the rehash happened afterward. Record the results as evidence for your change record, and confirm with your security team which hasher settings your ZITADEL deployment is configured with before go-live.
How the migration differs by user base and starting point
A consumer app with a single user pool and mostly email and password accounts is the most direct case. The main question is whether the Clerk export includes password hashes you can import, since ZITADEL's documented import path depends on hashed passwords that users can keep. Plan the cutover around a window in which new sign-ups and password changes are paused or mirrored, because a user created in one system after the export will not exist in the other.
- Export first: Pull the user list and hashes from the Clerk dashboard, then confirm that every hash type you received has a matching verifier in ZITADEL before you commit to a bulk import.
- Import in batches: Use the single-user or bulk import endpoints, and run a small test batch with a test account to confirm that the first login validates and rehashes the password.
- Freeze sign-ups during cutover: Decide how accounts created during the final export delta are reconciled, since a gap here creates support tickets.
- Rebuild the login screens: Clerk's prebuilt components will not carry over, so budget for ZITADEL's hosted login and your own account pages.
- Keep a fallback path: Confirm with your own tests whether just-in-time migration is a better fit for any users whose hashes cannot be imported.
Before switching, check a sample of migrated accounts for successful first logins and confirm the password reset flow works end to end.
A B2B product built on Clerk organizations has more moving parts than a consumer app. Each customer organization may carry its own roles, memberships and enterprise SSO connection, and ZITADEL structures this differently, using instances, organizations and projects. Mapping Clerk organizations to ZITADEL organizations is a design decision, and it should be settled before any user data moves, because it controls how tenant data and policies are isolated.
- Map the tenant model: Decide whether each Clerk organization becomes a ZITADEL organization inside one instance, and document how memberships and roles translate.
- Recreate enterprise connections: Rebuild each customer's SAML or OIDC identity provider as a ZITADEL identity provider, since each organization can use a different one, and test each with a pilot customer.
- Coordinate with customers: Enterprise SSO changes can affect customer IdP configuration, so schedule these with the customer's administrators rather than as a platform-only change.
- Sequence by tenant: Migrating one organization at a time reduces the blast radius, though you should confirm with your own environment whether the chosen instance layout supports that cleanly.
- Verify role and grant parity: Compare permissions for sample users in each organization before and after the move.
Before cutover, confirm that every enterprise connection has a tested login path and that each organization's administrators know the new login URL.
An app whose users mostly sign in with Google, GitHub, Apple or passkeys has less password data to move, and that changes both scope and risk. Social accounts are linked to the identity provider, not to a stored password, so the migration often focuses on re-linking identities and on passkey enrollment. Passkeys are bound to the relying party and origin, which means their handling needs to be planned rather than assumed to carry over.
- Check the export contents: Confirm what the Clerk export contains for social connections and passkey credentials, since passkeys generally cannot be exported as secrets and may need re-enrollment.
- Re-link social identities: Configure the same providers in ZITADEL and confirm that the provider's subject identifier matches what your users will see at login.
- Plan passkey re-enrollment: Tell users which sign-in method will replace their passkey and provide a fallback that does not lock them out.
- Confirm the domain and origin: Passkeys depend on the domain, so a hosting change can break existing credentials.
- Keep a password fallback where needed: ZITADEL supports password login alongside passkeys, which can ease the transition for users who have neither.
Before switching, test each sign-in method with a real account in a staging environment and confirm that account recovery works for users who lost access to their original method.
What drives cost and duration of the migration
This table lists the main drivers of effort in a Clerk to ZITADEL move, why each one matters and how to keep it down. Read it before requesting a quote, because the drivers you control are usually the ones that change scope most.
| Driver | Why it changes cost or effort | How to keep it down |
|---|---|---|
| User count and password hash format | Clerk's standard dashboard export includes hashed passwords, but you must confirm the hash algorithm for every user before import. ZITADEL needs a matching verifier for each algorithm, and users with unsupported or mixed hashes need a different path such as just-in-time migration. | Export a sample and confirm the hash format early. Ask whether all users share one algorithm, and remove inactive accounts before export. |
| Number of organizations and memberships | Clerk organizations, roles and memberships must map to ZITADEL instances, organizations and projects, with grants re-created. Each organization with its own roles adds mapping and testing work. | Agree the target structure on paper first. Consolidate unused organizations and reuse a small set of standard roles. |
| Enterprise SSO connections | Each SAML or OIDC connection configured in Clerk must be rebuilt as an identity provider in ZITADEL and tested with the customer's administrators, who often need coordinated change windows. | Inventory every connection and its owner. Migrate connections in batches and retire unused ones before the move. |
| Custom UI screens to replace | Clerk's prebuilt components (sign-in, sign-up, profile and organization switcher) are replaced by ZITADEL's hosted login, and any custom branding, copy or flows that the app built around them need redesign and retesting. | List every Clerk component in use. Keep the hosted login defaults where possible and limit custom branding to the agreed scope. |
| Integrations and webhooks | Session handling, user creation events, metadata sync and backend calls to Clerk's API all need replacement. Each webhook consumer must be found, rewritten and verified against ZITADEL's APIs. | Map every API call and webhook from the codebase and logs. Confirm which consumers are still active before scoping. |
| PostgreSQL operations | Self-hosted ZITADEL depends on PostgreSQL, with versions 14 through 18 supported. Backup, failover, patching and monitoring of the database become your team's recurring work after cutover. | Confirm the supported PostgreSQL version and existing database platform. Ask the implementation partner for a written operating model covering backup, restore testing and upgrades. |
| Testing scope | Login, password reset, MFA, passkeys, social login, SSO flows and first-login password rehashing each need test cases across user types. Gaps here usually surface as support tickets after cutover. | Define test cases from real user journeys, include failed-login and first-login rehash cases, and agree the exit criteria in writing. |
| Cutover and parallel running | Running Clerk and ZITADEL side by side, or phasing users, adds routing, session and data sync work. A single cutover is simpler but needs a tighter rollback plan. | Choose the cutover approach early. Ask what rollback looks like and who signs off each phase. |
What usually goes wrong and how to prevent it
Most failed Clerk-to-ZITADEL moves fail on the data and the edges of the application rather than on the server itself. The cards below cover the password, organization, session, redirect, metadata and database risks that tend to surface after cutover, with a prevention step for each.
Password hashes that force resets
If the export does not include password hashes, or the hash algorithm is not recorded, users will be locked out at first login and support volume will spike. ZITADEL imports hashed passwords with an algorithm value, so each hash must be paired with the correct algorithm before import. Check a sample of exported users against the source login before running the full import, and confirm with Clerk which hashing scheme your export uses. Verify one test login per algorithm before cutover.
Organization membership not mapped
Clerk organizations, memberships and roles do not map one-to-one onto ZITADEL's instances, organizations and projects. A user who belongs to two Clerk organizations can end up in the wrong ZITADEL organization or with no role at all, which breaks tenant access checks in the app. Build a written mapping table from each Clerk organization to a ZITADEL organization and project before import, and test that each tenant admin sees only their own users.
Broken frontend session handling
Clerk's prebuilt components manage tokens, session refresh and sign-out for you. When those components are replaced with ZITADEL's hosted login, the app may keep stale tokens, fail to refresh them, or leave users signed in after logout. Map every place the app reads the Clerk session, then test expiry, refresh, logout in one tab and login in another. Treat session logic as code that needs its own test cases, not as a UI swap.
Redirect URI mismatches
Each OIDC client in ZITADEL only accepts the redirect URIs and post-logout URIs registered for it. A missing staging URL, a trailing slash or a changed callback path will cause sign-in to fail for some environments only. Keep an inventory of every callback and logout URL the Clerk application uses, register them on the ZITADEL application for each environment, and test them in staging with the same hostnames used in production.
Lost user metadata
Clerk public and private metadata, custom attributes and some profile fields may not appear in a standard user export. If the application depends on them for plans, feature access or onboarding state, those values disappear silently at cutover. Pull metadata through the API, decide which fields move into ZITADEL user metadata or the application database, and reconcile counts field by field after the import.
Unplanned PostgreSQL operations
Self-hosted ZITADEL depends on PostgreSQL, and the supported database versions must match the release you deploy. Without a plan for backups, restores, connection limits, upgrades and monitoring, the identity service becomes a single point of failure for every login. Confirm the supported PostgreSQL version range for your ZITADEL release, define backup and restore tests before go-live, and assign an owner for database patching.
Questions buyers ask before moving from Clerk to ZITADEL
Do Clerk users keep their passwords when we move to ZITADEL?
Yes, if you can export the password hashes from Clerk and import them into ZITADEL, users keep their existing passwords. ZITADEL's import endpoints, ImportHumanUser and the admin ImportData bulk endpoint, accept a hashed password with a value and an algorithm, and bcrypt appears in the documented examples. On a migrated user's first login, ZITADEL checks the password with the matching verifier and then rehashes it with its configured hasher. Confirm with Clerk exactly which hash algorithm your instance stores and whether the dashboard export includes hashes for your plan, since that determines whether this path works for your user base.
What drives the cost of moving from Clerk to self-hosted ZITADEL?
The cost splits into components: infrastructure and PostgreSQL hosting you pay for each month, the one-time work to build the login screens and integrate your application, the migration of users and organizations, and the ongoing operation of ZITADEL itself. Costs rise with the number of applications you must rewire, the number of enterprise connections to rebuild, the amount of custom branding for the hosted login, and the availability you need for high availability setups. Clerk's own fees are billed per retained user and per enterprise connection, so ask Clerk for your current invoice breakdown before comparing. Ask any implementation partner for a fixed-scope quote built from a written list of these components.
How long does a Clerk to ZITADEL migration take?
The timeline depends on scope, not on a fixed duration. The main variables are how many frontends use Clerk's prebuilt components, how many organizations and enterprise connections need rebuilding, whether you can run both systems in parallel, and how many users need a staged cutover. ZITADEL documents just-in-time migration as one approach, which can shorten the window because users move when they first sign in, but it also requires that you keep the old hashes available. No duration is supplied for this migration, so ask your implementation partner for a timeline tied to a written scope and ask Clerk how long it takes to deliver the export you need.
Can our in-house team migrate from Clerk to ZITADEL without outside help?
A capable team can run the migration in-house if it has experience with OIDC, PostgreSQL, container deployment and frontend login flows. The harder parts are usually not the data export but the replacement of Clerk's prebuilt components with ZITADEL's hosted login, the rebuilding of organization and role mapping, and the production operation of an identity system. Your team needs to own key rotation, backups, upgrades and incident response after cutover. Decide early which of these work you will keep, and ask any outside partner to state in writing which parts of the scope it covers and which remain with your staff.
What does the migration need from our engineering and security teams?
Expect to provide several inputs before work starts:
- Access to a Clerk account with an owner or admin role to run the export and pull organization and metadata through the API
- Engineers who can change the authentication code in each application and test sign-in, sign-out and session handling
- Security review of hosting, network access, database configuration and the handling of exported files that contain hashes
- A decision on which enterprise identity providers will be brokered and who controls their configuration
Ask for these inputs as a written list in the scope document so that responsibilities are clear on both sides.
How are Clerk organizations and enterprise SSO connections rebuilt in ZITADEL?
ZITADEL structures tenants as instances, organizations inside instances where projects and users live, and projects that group applications, roles and grants. Clerk organizations map most naturally to ZITADEL organizations, with members and roles recreated through the import process. ZITADEL can federate login with OIDC or SAML identity providers, LDAP, Entra ID, Okta and others, and each customer organization can use a different identity provider. Each enterprise connection must be recreated and tested with the customer's identity provider administrator, because certificates, redirect URIs and attribute mappings differ per connection. Confirm the mapping for every Clerk organization before cutover.
What happens to our Clerk data after we cut over?
Once users sign in through ZITADEL, the Clerk tenant stops being your system of record for login, but it still holds data you may need to keep. Decide what to retain for audit, support and contractual reasons, such as user records, session logs and organization history, and how long to keep them. Before you cancel the subscription, confirm the export contents in writing with Clerk, verify that imported counts match the export, and confirm how Clerk deletes data when you close the account. Your privacy and legal teams should approve the retention plan before the old tenant is closed.
Does ZITADEL's license change how we can use it after a migration?
ZITADEL's core, Console and hosted login are licensed under the GNU Affero General Public License 3.0 since version 3.0, released on 31 March 2025. APIs, SDKs, proto definitions, examples, documentation, Helm charts and Terraform configurations remain Apache 2.0. The AGPL includes obligations for modified versions that users interact with over a network, so if you change ZITADEL's core or hosted login, have legal counsel review your obligations before you deploy. Confirm the current license terms in the ZITADEL repository and with your legal team, since they affect how you customize the login pages.
How DeployOpen scopes and runs a Clerk to ZITADEL migration
DeployOpen plans, implements, integrates, hardens, backs up and documents self-hosted ZITADEL inside your own infrastructure, whether that is your cloud account, a data center or an air-gapped network. Most engagements run as a fixed scope, with the systems, deliverables and timelines agreed in writing before any work starts. For a Clerk migration, that written scope is where the decisions get made: which Clerk instance and applications move, how users and their hashed passwords are exported and imported, how Clerk organizations map to ZITADEL instances, organizations and projects, which enterprise connections are rebuilt as identity providers, and which Clerk components are replaced by ZITADEL's hosted login. Ask for the scope to name each of these items explicitly, along with the environments it covers (staging and production) and the cutover approach.
DeployOpen does not publish a price list. A quote follows from the written scope, so the inputs that move cost are the number of applications, the number of organizations and enterprise connections, the volume and complexity of the user import, the number of custom login and account screens to rebuild, and the hosting and high-availability design you choose for PostgreSQL and ZITADEL. Ongoing support, upgrades and continuous testing are available as retainers, which can be scoped separately from the migration itself. When you request a quote, ask for the one-time and recurring components to be shown separately and for the assumptions behind each line to be stated.
DeployOpen prepares systems, controls and evidence for compliance assessments, such as configuration records, access settings, backup and restore tests and change logs. It does not issue audit reports, attestations or certifications; independent auditors and certification bodies perform those assessments. Confirm early which evidence your auditor will require, because login logs, retention settings and the record of password hash handling during the import are easier to capture while the migration is planned than to reconstruct afterward.
