Clerk migration: keep legacy user ids working with an external_id claim alias

external_id claim alias during migration

The idea

Your old system gave every user an id your database uses as a foreign key. Clerk generates new ids on import. Instead of rewriting your tables on day one, store the old id as external_id and make the session token carry it.

The order

1. During import, set externalid on every user to the legacy provider id (Auth0 userid, Firebase uid, whatever you had).

2. In the dashboard go to Sessions, Customize session token, Claims editor, and add a claim that prefers the legacy id: {"userId": "{{user.external_id || user.id}}"} Merge it with any claims you already have.

3. New users with no external_id fall back to the native Clerk id, so the same backend code works for migrated and new users.

4. Later, when you are ready, backfill your tables to the native ids and drop the alias claim.

Checklist

• Verify the alias on a migrated user and a brand-new user. The new user must get the native id, not an empty string.

• This alias exists for backends that cannot change lookup columns yet. If you own the backend and the user base is small, skip the alias and do a clean column swap instead. Less machinery, less to forget.

• The alias claim is a compatibility shim. Record a cutover date and a ticket for removing it, or it becomes permanent tech debt.

Verified live against the Clerk docs 2026-09-26 at https://clerk.com/docs/deployments/migrate-overview. Clerk's migration overview documents storing previous ids as externalid and enriching the session token with an externalid-or-native-id claim via the sessions page.