Preserve application ownership during an auth migration

Moving authentication away from Clerk must preserve which person owns each application record. Exporting user emails alone cannot do that. Keep an explicit relationship between the Clerk user ID, the destination Own Auth user, and the projects, subscriptions, organisations, and permissions that already belong to that person.

The Clerk migration guide uses a mapping from the source user ID to the Own Auth user ID. Clerk's dashboard can export users and password hashes, but the documented Own Auth importer does not import those hashes. Identity mapping therefore remains distinct from credential compatibility and the user's first successful destination sign in. This article focuses on preserving application ownership through that transition.

Inventory the identifiers that actually own records

Start with the application's saved relationships. A project might store a provider user ID in its owner field. A subscription may refer to a separate account record. Organisation membership can use another table, while uploaded files may embed the original ID in object keys or ownership metadata. Each relationship needs an explicit destination after the migration.

Do not assume every field named user_id represents the same identity. An external provider subject, an application account ID, and an imported Own Auth user ID can be different values. Record which system issued each one and which records depend on it. The migration should preserve those relationships deliberately rather than treating matching field names as a schema guarantee.

Separate identity mapping from account matching

Use the source provider and source user ID together as the durable import key. An email address can help detect a conflict, but it should not silently merge two existing accounts. If the destination email already belongs to another person or an unrelated earlier import, stop that record for review instead of assigning the source person's projects to it.

This is especially important for social accounts. The provider's subject identifies the external account. A shared or changed email address does not establish that two provider identities are the same person. Keep the supported linking policy separate from migration matching, and preserve the provenance needed to explain why a source identity was connected to a destination account.

Choose whether application IDs change

If the application already has its own stable account ID, it may be able to retain that ID and attach the new authentication identity to it. That can reduce the number of application relationships that must change. The important requirement is that the backend resolves the new verified identity to the correct application account before authorizing a query.

If records directly reference the old provider's user IDs, define how each relationship will move or be resolved. Foreign keys, unique constraints, row security policies, export paths, and background jobs all need the same answer. A browser that displays the right profile does not prove that a worker or download route uses the new identity mapping.

Keep imports safe to repeat

A migration can stop after creating a user but before saving the mapping row. A safe rerun needs to recognize that partial result without creating another user or adopting an unrelated one. The current guides attach source migration metadata and verify it when recovering an existing email match. That is a concrete recovery check, not permission to merge every matching address.

Preserve the original source ID and import facts. Do not rewrite those facts to satisfy a later validation rule. Record conflicts separately so a reviewer can resolve the real ownership question. A completed count is meaningful only when it represents the expected people with their expected records, not merely the number of insert statements that succeeded.

Plan the period when both systems exist

An export is a snapshot. Accounts, memberships, or addresses can change while the new system is being prepared. Choose a cutover method that accounts for those changes: a controlled pause, a tracked final update, or a defined gradual transition. State which system remains authoritative for each record during that period.

Session migration is a separate problem. An old access token or provider cookie does not become an Own Auth session by appearing beside a mapped user. Establish the new session through a supported authentication path, and decide when old credentials stop granting access. If a backend continues accepting the old token, deleting the old browser cookie alone does not complete that cutover.

Check ownership through real application actions

For representative imported accounts, sign in through the destination and open existing projects, organisation settings, billing records, and downloads. Verify both allowed and denied actions. A user must retain their own data and remain unable to access another user's records. Include a user with several organisations and a user whose email changed after the original export.

Also run the importer again and recover one intentionally interrupted record. The expected result is the same destination user and the same application ownership. Keep the mapping until every dependent application path has been accounted for. Continue with the Clerk migration guide or Supabase migration guide for provider specific export and cutover details.