# Firebase Auth to Clerk: export and import migration
## The order
1. Export users with the Firebase CLI auth export. The export includes
password hashes with Firebase's scrypt parameters and the salt. Keep
those parameters; they are what the password_hasher declaration needs.
2. Transform into the migration tool's JSON or CSV shape: external_id gets
the Firebase uid, email_addresses carry email plus verified status,
displayName and photoURL map to name and image fields, custom claims go
into public_metadata.
3. Import through the CreateUser backend endpoint declaring the Firebase
password hasher. Clerk transparently upgrades to bcrypt on first login.
4. Respect the CreateUser rate limit. The migration tool handles pacing and
error retries; hand-rolled scripts usually learn about the limit the
hard way.
5. Trial the import on a development instance with a small batch before the
full run.
## The Firebase-specific traps
- Firebase custom claims are not Clerk session claims. Map them into
public_metadata, then expose what the app needs via custom session token
claims as a separate step after migration.
- Phone-auth users: their primary identifier is a phone number, not an
email. Decide before import whether email or phone is the canonical
identifier in Clerk, because sign-in flows key off it.
- Anonymous Firebase users cannot migrate. Decide what happens to their
data (attach to a new account on first real sign-in, or drop it).
## Checklist
- A migrated email/password user signs in with the old password on the
first attempt.
- Custom claims from Firebase appear in Clerk public_metadata for sampled
users.
- User count in Firebase matches user count in Clerk, minus the anonymous
accounts you decided to drop.