Bulk import users: job format, password hashes, and verification strategy

Bulk user import

1. Format

Management API POST /api/v2/jobs/users-imports: multipart with the connectionid and a JSON file of users. Fields: email, emailverified, appmetadata, usermetadata, and password_hash for password preservation.

2. Password hashes

Auth0 accepts common hash formats (bcrypt, etc.) in the import. If your hashes are portable, users keep their passwords: zero-friction migration. If not (custom scheme), import without hashes and trigger password-reset emails, or run a lazy migration via a custom database connection that checks the old store on first login.

Set email_verified honestly: true only if the source verified it. Importing unverified emails as verified is a security hole.

3. Run

The job is async: POST returns a job id; poll GET /api/v2/jobs/[job id] until complete. The job summary reports created/updated/failed counts. Download the error file for failures; common causes are malformed emails and duplicate emails within the file.

4. Verify

• Spot-check users in the dashboard: metadata intact, verified flags correct.
• Test login with a migrated account (password preserved) and a reset-flow account.
• Confirm the connection's applications are enabled before users try to log in.

5. Cutover

Import during low traffic, keep the old system read-only, and have the password-reset template ready for the hash-less cohort. Communicate the plan; "just try logging in" plus a clear reset path beats a surprise.

Checklist

• Hash portability decided BEFORE the import, not during.
• Failure file reviewed; every failed user accounted for.

Auth0's Management API documents the users-imports job endpoint, the JSON schema including password_hash, and job status polling. Verified against live docs 2026-09-26.