Skip to main content
You can bulk import existing user data into an Auth0 database connection. This can be useful for migrating users from an existing database or service to Auth0. To bulk import user data, you first create a user data file in the JSON format Auth0 expects and then start a job to import that data using the Dashboard or the Management API.

​
Prerequisites

​
1. Create the user data file

First, format your existing user data into JSON for import into Auth0 following the structure defined in the user data JSON schema and property reference. The following considerations may be helpful as you create the user data file:
  • The file size limit for a bulk import is 500KB. If your data exceeds this limit, you need to divide your user data into multiple smaller files to upload across multiple jobs. As a guideline, approximately 1,000 users with fewer than 10 metadata fields per user is typically under the file size limit.
  • If you’re starting with an Auth0 user data export:
    • Bulk imports support JSON format, but user exports generated by Auth0 are in NDJSON format. You can convert from NDJSON to JSON using tools like jq.
    • Bulk imports automatically add the auth0| prefix to imported user IDs, but user exports generated by Auth0 already have the auth0| prefix on user IDs.
    To keep the same user IDs, remove the auth0| prefix from all imported user IDs. Otherwise, the user IDs will have the prefix twice (auth0|auth0|<user_id>).
  • You can import user data with passwords hashed by a supported algorithm. Users with passwords hashed by unsupported algorithms must reset their password when they log in for the first time after the bulk import. If a user did not log in with the custom_password_hash you imported initially, you can update it by resubmitting the user data with a different value for custom_password_hash in a new job with upserts enabled.

​
2. Import the user data into your database connection

To import user data using the Auth0 Dashboard:
  1. Go to Dashboard > User Management > Users.
  2. In the top right corner of the page, select Import/Export Users to go to the Import/Export Users page.
  3. Select Import Users to go to the Import Users page.
  4. Under Users JSON file, select + Choose File and upload the user data JSON file.
  5. Under Connection, open the drop-down menu and select the database connection where you want to import the user data.
  6. Optionally, check Upsert pre-existing users in connection. When an imported user matches an existing user in the database connection, you can choose whether or not to upsert the data:
    • By default, upserts are disabled. Imports of users that match on email address, user ID, phone, or username fail.
    • With upserts enabled, imports of users matching on email address update all upsertable attributes.
  7. Optionally, check Send completion email to all tenant owners. When enabled, this sends a completion email to all tenant administrators when the job succeeds or fails.
  8. To submit the job, select Import Users.

​
3. Check job status

To check the status of a job:
  1. Go to Dashboard > User Management > Users.
  2. In the top right corner of the page, select Import/Export Users to go to the Import/Export Users page. Once you start at least one job, this page lists your submitted jobs.
  3. To view more information about a job, select More info next to any job.
Job statuses include Job creation failed, Job created, user import failed, and Job created, user import succeeded.
Jobs fail if there is an error, but not if there is invalid user information (like an invalid email).

​
Limits

  • There is a limit of two concurrent import jobs per tenant.
  • User import jobs time out after two (2) hours. If a job does not complete within this time frame, it is marked as failed.
  • All job-related data is automatically deleted after 24 hours.
  • Duplicated user entries in the import file cause an error. They do not cause an import followed by an upsert.
  • Upserts do not merge user_metadata or app_metadata. The existing metadata is completely overwritten with the new metadata.

​
Best practices for large-scale migrations

When importing large quantities of user data (requiring 10 or more jobs), we recommend the following strategies:
  • Use a job scheduler framework (such as Bull or Agenda). This lets you:
    • Enforce the required concurrency limit.
    • Include a retry strategy to handle network connection drops and temporary failures.
    • Store job results and error details beyond the deletion window.
  • Don’t interrupt imports on single user failures. Instead, implement a “finalizer” job that reviews all spawned jobs and collects failed records into a new file. Fix any errors in the collected failed records and import them as a new job.
  • Use caution when enabling upsert mode. Imports with upsert are slower than standard imports and do not merge metadata. Use upsert mode when you need to update existing users and understand these limitations.