# 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 external_id on every user to the legacy provider id
(Auth0 user_id, 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.