Migrate Users Using the Password Hashes Export in Auth0

Last Updated: Sep 16, 2026

Overview

Migrate users using the Password Hashes export from Auth0 by converting the Newline Delimited JSON (NDJSON) file into a standard JSON array. Merge the password hashes with the user metadata, then import the data using the Bulk Import Users API.

Applies To

Auth0
Password Hashes Export
User Migration
Connections

Solution

What is the data format of the Password Hashes export?

The provided file uses the Newline Delimited JSON (NDJSON) format (New line delimited JSON). Review the following JSON structure to understand the export file format.

{ ... one user... }
{ ... another user ... }
{ ... and so on ... }

Each user object contains specific properties. Review the following JSON structure for a sample single user object.

{
"_id":"5dea9f9c82dd7c0e76e4ec93",
"email_verified":false,
"email":"user@example.com",
"passwordHash":"$2b$10$.qHPp/srq...REDACTED...",
"password_set_date":{"$date":"2019-12-06T18:36:12.412Z"},
"tenant":"example-tenant-name",
"connection":"Username-Password-Authentication",
"_tmp_is_unique":true,
"identifiers":[{"type":"email","value":"user@example.com","verified":false}],
"alt_id":"euclid"
}

Every user contains an _id field, while the alt_id field is optional. The alt_id field appears for users originating from a custom database that provides the user ID, or for users created with the Management API v2 using a custom user ID.

In the previous example, the user identifier is auth0|euclid. If the alt_id field is absent, the full user_id is auth0|5dea9f9c82dd7c0e76e4ec93.

The connection parameter indicates the user's origin when exporting from multiple databases. Root attributes such as email and email_verified may not appear in the export for some users, but these attributes remain consistently available within the identifiers array as email and verified.

Can the export file be imported directly into Auth0?

The Bulk Import Users API and the Users Import Extension do not accept the NDJSON format. Review the Bulk User Import Database Schema and Examples for the full specification. Review the import requirements to ensure the data formats correctly for the Bulk Import Users API.

The import file size cannot exceed 500 KB.
The expected format is a JSON array, not NDJSON.
Provide a user_id field with the value found in the exported user’s alt_id (if present) or the $oid value to import the original user IDs.

Apply the following JSON structure to format the sample user with the alt_id and keep the same user ID.

[
{
"user_id":"euclid",
"email_verified":false,
"email":"user@example.com",
"password_hash":"$2b$10$.qHPp/srq...REDACTED..."
},
{...}
]

Apply the following JSON structure to format the sample user without an alt_id and keep the same user ID.

[
  {
    "user_id":"5dea9f9c82dd7c0e76e4ec93",
    "email_verified":false,
    "email":"user@example.com",
    "password_hash":"$2b$10$.qHPp/srq...REDACTED..."
  },
  {...}
]

Convert the data using the jq command-line JSON processor.

Use the jq tool to convert the data into the required format.

Execute the following command to read an input file (input.json), pipe it through jq filters, and write it to an output file (output.json) ready for import.

cat input.json | jq '{user_id: (if has("alt_id") then .alt_id else ._id end), email, username, email_verified, password_hash: .passwordHash}' | jq -s 'del(.[][] | nulls)' > output.json

The first jq pass selects relevant fields, and the second pass removes null values and transforms the input into a single array. The command selects the alt_id as the user ID, and uses the _id if alt_id is unavailable.

Replace ._id with null in the following command to use the alt_id if present and allow Auth0 to assign a random user_id if the alt_id is absent.

cat input.json | jq '{user_id: (if has("alt_id") then .alt_id else null end), email, username, email_verified, password_hash: .passwordHash}' | jq -s 'del(.[][] | nulls)' > output.json

How is metadata added or migrated?

The password hashes export provided by Auth0 Support does not include user metadata fields. Export the data separately using the regular bulk user export from the extension or the Management API v2. Merge the exported metadata with the password hashes provided by Auth0 Support to ensure the final import file contains all data.

Apply the following JSON structure to format the merged data.

[
{
"user_id":"5dea9f9c82dd7c0e76e4ec93",
"email_verified":false,
"email":"user@example.com",
"password_hash":"$2b$10$.qHPp/srq...REDACTED...",
"given_name":"Nicolás",
"app_metadata": {
},
"user_metadata": {
}
},
{...}
]

Resolve common issues encountered during the export process.

Large exports may include empty jsonlines files after decompression. Auth0 expects this behavior due to how it runs the query, and empty files do not indicate missing data.

The macOS Archive utility may display an Unable to expand <EXPORT_FILENAME>.zip into <DESTINATION_FOLDER_NAME> error. Use a different archive manager tool to bypass this error.