**TL;DR:** Firebase exports password hashes in its own scrypt flavor, so the password_hasher declaration matters even more here. Get the export format right once and the rest is the same export/import pipeline as any other provider. Keep those parameters; they are what the password_hasher declaration needs.

## The fix

**TL;DR:** Firebase exports password hashes in its own scrypt flavor, so the password_hasher declaration matters even more here. Get the export format right once and the rest is the same export/import pipeline as any other provider. Keep those parameters; they are what the password_hasher declaration needs.

# 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.

## When to use this

- This covers exactly what the title says: Firebase Auth to Clerk migration.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.

## When not to use this

- You are doing a different workflow with Firebase; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.

## Compatibility

- Not pinned to a specific version; follows current Firebase behavior.