User Data JSON Schema for Bulk User Imports

The user data file used for bulk user imports must be in JSON format. It must contain an array of user objects matching the specified schema.

User JSON schema

The following JSON schema describes valid users:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The user's email address.",
      "format": "email"
    },
    "email_verified": {
      "type": "boolean",
      "default": false,
      "description": "Indicates whether the user has verified their email address."
    },
    "phone_number": {
      "type": "string",
      "description": "The user's phone number. Must be in E.164 format, including the country code, such as `+12125550001`."
    },
    "phone_verified": {
      "type": "boolean",
      "default": false,
      "description": "Indicates whether the user has verified their phone number."
    },
    "user_id": {
      "type": "string",
      "description": "The user's unique identifier. This will be prepended by the connection strategy."
    },
    "username": {
      "type": "string",
      "description": "The user's username."
    },
    "given_name": {
      "type": "string",
      "description": "The user's given name."
    },
    "family_name": {
      "type": "string",
      "description": "The user's family name."
    },
    "name": {
      "type": "string",
      "description": "The user's full name."
    },
    "nickname": {
      "type": "string",
      "description": "The user's nickname."
    },
    "picture": {
      "type": "string",
      "description": "URL pointing to the user's profile picture."
    },
    "blocked": {
      "type": "boolean",
      "description": "Indicates whether the user has been blocked."
    },
    "password_hash": {
      "type": "string",
      "description": "Hashed password for the user. Passwords should be hashed using bcrypt $2a$ or $2b$ and have 10 saltRounds."
    },
    "custom_password_hash": {
      "type": "object",
      "description": "A more generic way to provide the users password hash. This can be used in lieu of the password_hash field when the users password hash was created with an alternate algorithm. Note that this field and password_hash are mutually exclusive.",
      "properties": {
        "algorithm": {
          "type": "string",
          "enum": [
            "argon2",
            "bcrypt",
            "hmac",
            "ldap",
            "md4",
            "md5",
            "sha1",
            "sha256",
            "sha512",
            "pbkdf2",
            "scrypt"
          ],
          "description": "The algorithm that was used to hash the password."
        },
        "hash": {
          "type": "object",
          "properties": {
            "value": {
              "type": "string",
              "description": "The password hash."
            },
            "encoding": {
              "type": "string",
              "enum": [
                "base64",
                "hex",
                "utf8"
              ],
              "description": "The encoding of the provided hash. Note that both upper and lower case hex variants are supported, as well as url-encoded base64."
            },
            "digest": {
              "type": "string",
              "description": "The algorithm that was used to generate the HMAC hash",
              "enum": [
                "md4",
                "md5",
                "ripemd160",
                "sha1",
                "sha224",
                "sha256",
                "sha384",
                "sha512",
                "whirlpool"
              ]
            },
            "key": {
              "type": "object",
              "description": "The key that was used to generate the HMAC hash",
              "required": [
                "value"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "The key value"
                },
                "encoding": {
                  "type": "string",
                  "enum": [
                    "base64",
                    "hex",
                    "utf8"
                  ],
                  "default": "utf8",
                  "description": "The key encoding"
                }
              }
            }
          }
        },
        "salt": {
          "type": "object",
          "properties": {
            "value": {
              "type": "string",
              "description": "The salt value used to generate the hash."
            },
            "encoding": {
              "type": "string",
              "enum": [
                "base64",
                "hex",
                "utf8"
              ],
              "default": "utf8",
              "description": "The encoding of the provided salt. Note that both upper and lower case hex variants are supported, as well as url-encoded base64."
            },
            "position": {
              "type": "string",
              "enum": [
                "prefix",
                "suffix"
              ],
              "default": "prefix",
              "description": "The position of the salt when the hash was calculated. For example; MD5('salt' + 'password') = '67A1E09BB1F83F5007DC119C14D663AA' would have \"position\":\"prefix\"."
            }
          },
          "required": [
            "value"
          ]
        },
        "password": {
          "type": "object",
          "properties": {
            "encoding": {
              "type": "string",
              "enum": [
                "ascii",
                "utf8",
                "utf16le",
                "ucs2",
                "latin1",
                "binary"
              ],
              "default": "utf8",
              "description": "The encoding of the password used to generate the hash. On login, the user-provided password will be transcoded from utf8 before being checked against the provided hash. For example; if your hash was generated from a ucs2 encoded string, then you would supply \"encoding\":\"ucs2\"."
            }
          }
        },
        "keylen": {
          "type": "integer",
          "description": "Desired key length in bytes for the scrypt hash. Must be an integer greater than zero. Required when algorithm is set to scrypt."
        },
        "cost": {
          "type": "integer",
          "default": 16384,
          "description": "CPU/memory cost parameter used for the scrypt hash. Must be a power of two greater than one. Only used when algorithm is set to scrypt."
        },
        "blockSize": {
          "type": "integer",
          "default": 8,
          "description": "Block size parameter used for the scrypt hash. Must be a positive integer. Only used when algorithm is set to scrypt."
        },
        "parallelization": {
          "type": "integer",
          "default": 1,
          "description": "Parallelization parameter used for the scrypt hash. Must be a positive integer. Only used when algorithm is set to scrypt."
        }
      },
      "required": [
        "algorithm",
        "hash"
      ],
      "additionalProperties": false
    },
    "app_metadata": {
      "type": "object",
      "description": "Data related to the user that does affect the application's core functionality."
    },
    "user_metadata": {
      "type": "object",
      "description": "Data related to the user that does not affect the application's core functionality."
    },
    "mfa_factors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "totp": {
            "type": "object",
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^[A-Z2-7]+$",
                "description": "The OTP secret is used with authenticator apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass). It must be supplied in un-padded Base32 encoding, such as: JBTWY3DPEHPK3PNP"
              }
            },
            "additionalProperties": false,
            "required": [
              "secret"
            ]
          },
          "phone": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "pattern": "^\\+[0-9]{1,15}$",
                "description": "The phone number for SMS MFA. The phone number should include a country code and begin with +, such as: +12125550001"
              }
            },
            "additionalProperties": false,
            "required": [
              "value"
            ]
          },
          "email": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "format": "email",
                "description": "The email address for MFA"
              }
            },
            "additionalProperties": false,
            "required": [
              "value"
            ]
          }
        },
        "maxProperties": 1,
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 10
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

User object properties

object

upsertable

Data that can affect the application’s core functionality or what the user can access. Data stored in app_metadata cannot be edited by users. This may include things such as support plans, roles or access groups.For more information about metadata, read Understand How Metadata Works in User Profiles.

Show prohibited properties

app_metadata cannot contain the following properties:

__tenant
_id
blocked
clientID
created_at
email_verified
email
globalClientID
global_client_id
identities
lastIP
lastLogin
loginsCount
metadata
multifactor_last_modified
multifactor
updated_at
user_id

boolean

Whether the user has been blocked.

string

required

The user’s email address.

boolean

default:false

upsertable

Indicates whether the user has verified their email address. Set to false by default if email is updated by upsert but not email_verified.

string

upsertable

The user’s family name.

string

upsertable

The user’s given name.

string

upsertable

The user’s full name.

string

upsertable

The user’s nickname.

string

upsertable

URL pointing to the user’s profile picture.

string

The user’s phone number. Must be in E.164 format, including the country code, such as +12125550001.

boolean

default:false

Indicates whether the user has verified their phone number.

string

The user’s unique identifier. This is prepended by the connection strategy.

object

upsertable

Data that does not impact what users can or cannot access, such as work address, home address, or user preferences.For more information about metadata, read Understand How Metadata Works in User Profiles.

string

The user’s username.

string

Hashed password for the user’s connection.When users are created, Auth0 uses bcrypt to secure the password. Importing hashed passwords lets users keep their passwords for a smoother experience. Compatible passwords should be hashed using bcrypt $2a$ or $2b$ and have 10 saltRounds.This property can only be provided when the user is first imported and cannot be updated later.

object

upsertable

A more generic way to provide the user’s password hash.You can use this field instead of the password_hash field when the user’s password hash was created with an alternate algorithm. This field and password_hash are mutually exclusive.During the bulk import process, you can update the custom_password_hash if the user did not login using the initially imported custom_password_hash.

Show children

string

required

The algorithm used to hash the password.Auth0 supports the following algorithms:

When the algorithm is set to argon2:

hash.encoding must be utf8.
hash.salt is not allowed.
hash.value must be in PHC string format, specified in P-H-C / phc-string-format on GitHub. It also must conform to the requirements specified in Auth0 / magic on GitHub.
hash.value must include the base64 encoded salt (as specified in the PHC documentation).

When the algorithm is set to bcrypt:

hash.encoding must be utf8.
hash.salt is allowed in conjunction with with salt encoding and position.
hash.value must include one of these prefixes:
- $2a$
- $2b$
- $2y$
Other prefixes, such as $2$ , $sha1$ , and $2x$ , are not supported at this time.

For example, this was generated from the string hello using a cost parameter of 10: $2b$10$nFguVi9LsCAcvTZFKQlRKeLVydo8ETv483lkNsSFI/Wl1Rz1Ypo1KThe bcrypt algorithm processes a maximum of 72 bytes of input when computing password hashes or performing comparisons and the length of salt.value counts towards the 72-byte input limit. Any input beyond the 72 byte limit is truncated; for example, if the salt consumes 10 bytes, the maximum password length for hashing or comparison is 62 bytes.Passwords longer than the reduced limit are truncated, potentially weakening password strength or introducing hash collisions. Always validate password lengths before hashing.

When the algorithm is set to hmac:

hash.encoding must be either hex or base64.
hash.digest is required and must be one of:
- md4
- md5
- ripemd160
- sha1
- sha224
- sha256
- sha384
- sha512
- whirlpool
hash.key.value is required.
hash.key.encoding must be either base64 or hex or utf8.

When the algorithm is set to ldap (RFC-2307 "userPassword"):

hash.encoding must be utf8.
hash.salt is not allowed.
hash.value must adhere to the format outlined in RFC-2307 section-5.3 on IETF Datatracker.
The scheme must be one of md5|smd5|sha*|ssha*. See here for more info. The crypt scheme is not supported due to system/implementation dependent behavior. To learn more, read Open LDAP Admin Guide - 14.4.2. CRYPT password storage scheme.

When the algorithm is set to md4, md5, sha1, sha256, or sha512:

hash.encoding must be either hex or base64.

When the algorithm is set to pbkdf2:

hash.encoding must be utf8.
hash.salt is not allowed.
hash.value should be in PHC string format, specified in P-H-C / phc-string-format on GitHub.
hash.value must include the B64 encoded salt (base64 omitting padding characters =, as specified in the PHC documentation).
hash.value should include i (iterations) and l (keylen) parameters. If these parameters are omitted, they will default to i=100000 and l=64.
The id should be in a pbkdf2-<digest> format (pbkdf2-sha512, pbkdf2-md5, etc). The supported digests are:
- RSA-MD4
- RSA-MD5
- RSA-MDC2
- RSA-RIPEMD160
- RSA-SHA1
- RSA-SHA1-2
- RSA-SHA224
- RSA-SHA256
- RSA-SHA384
- RSA-SHA512
- md4
- md4WithRSAEncryption
- md5
- md5WithRSAEncryption
- mdc2
- mdc2WithRSA
- ripemd
- ripemd160
- ripemd160WithRSA
- rmd160
- sha1
- sha1WithRSAEncryption
- sha224
- sha224WithRSAEncryption
- sha256
- sha256WithRSAEncryption
- sha384
- sha384WithRSAEncryption
- sha512
- sha512WithRSAEncryption
- ssl3-md5
- ssl3-sha1
- whirlpool

When the algorithm is set to scrypt:

hash.encoding must be either hex or base64.

integer

required

Desired key length in bytes for the scrypt hash. Must be an integer greater than zero.

integer

default:16384

CPU/memory cost parameter used for the scrypt hash. Must be a power of two greater than one.

integer

default:8

Block size parameter used for the scrypt hash. Must be a positive integer.

integer

default:1

Parallelization parameter used for the scrypt hash. Must be a positive integer.

object

required

Show children

string

The password hash.

string

The encoding of the provided hash. Must be one of:

base64
hex
utf8

Upper and lower case hex variants are supported, as well as url-encoded base64.

string

The algorithm used to generate the HMAC hash. Must be one of:

md4
md5
ripemd160
sha1
sha224
sha256
sha384
sha512
whirlpool

object

The key used to generate the HMAC hash.

Show children

string

required

The key value.

string

default:"utf8"

The key encoding. Must be one of:

base64
hex
utf8

object

Show children

string

required

The salt value used to generate the hash.

string

default:"utf8"

The encoding of the provided salt. Must be one of:

base64
hex
utf8

Upper and lower case hex variants are supported, as well as url-encoded base64.

string

default:"prefix"

The position of the salt when the hash was calculated.

object

string

default:"utf8"

The encoding of the password used to generate the hash. Must be one of:

ascii
utf8
utf16le
ucs2
latin1
binary

On login, the user-provided password will be transcoded from password.encoding before being checked against the provided hash. For example, if your hash was generated from a ucs2 encoded string, then you would set: "encoding": "ucs2"

array

The multi-factor authentication (MFA) that can be used to authenticate this user. Importing enrollments prevents the need for users to re-enroll in MFA after they’re imported.The supported enrollment factors are email, SMS, and TOTP.

Show children

object

string

required

The email address for MFA.

object

string

required

The phone number for SMS MFA. Must have a country code and begin with +, such as "+12125550001".

object

string

required

The OTP secret used with authenticator apps (like Google Authenticator, Microsoft Authenticator, Authy, 1Password, or LastPass). Must be in un-padded Base32 encoding, for example: "JBTWY3DPEHPK3PNP"

User data JSON examples

Basic example

A file with the following contents is valid:

[
  {
    "email": "john.doe@example.com",
    "email_verified": false,
    "app_metadata": {
      "roles": ["admin"],
      "plan": "premium"
    },
    "user_metadata": {
      "theme": "light"
    }
  }
]

Custom password hash examples

Some example users with hashes provided:

[
  {
    "email": "antoinette@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "md4",
      "hash": {
        "value": "AbuUujgF0pPPkJPSFRTpmA==",
        "encoding": "base64"
      }
    }
  },
  {
    "email": "mary@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "sha256",
      "hash": {
        "value": "d24e794fce503c3ddb1cd1ba1dd5d9b250cf9917336a0316fefd87fecf79200f",
        "encoding": "hex"
      },
      "salt": {
        "value": "abc123",
        "position": "prefix"
      }
    }
  },
  {
    "email": "velma@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "bcrypt",
      "hash": {
        "value": "$2b$10$C9hB01.YxRSTcn/ZOOo4j.TW7xCKKFKBSF.C7E0xiUwumqIDqWUXG"
      }
    }
  },
  {
    "email": "edward@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "argon2",
      "hash": {
        "value": "$argon2id$v=19$m=65536,t=2,p=1$J6Q/82PCyaNpYKRELJyTZg$m04qUAB8rexWDR4+/0f+SFB+4XMFxt7YAvAq2UycYos"
      }
    }
  },
  {
    "email": "terrell@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "pbkdf2",
      "hash": {
        "value": "$pbkdf2-md4$i=100000,l=64$+N375B8q0Fw$fp2R9KAM4hK/votGHC5Fu+jhqbxUD8+Nic/EMSGvNC3UP/k7wSHI0uXluHRSkZfl/BOheYqNOemayG90ZaSSQw",
        "encoding": "utf8"
      }
    }
  },
  {
    "email": "cecil@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "pbkdf2",
      "hash": {
        "value": "$pbkdf2-sha512$i=100000,l=64$KNyFsA2rWoE$I2CQGI9H0JxdDf3kERRI97kPCGxh0KWBIV3MxyaS191gDGfzVBGyS4BibhgqWQ0/ails8mHuU9ckASxHOOq58w"
      }
    }
  },
  {
    "email": "sean@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "ldap",
      "hash": {
        "value": "{SSHA384}/cgEjdoZh85DhurDeOQEMO1rMlAur93SVPbYe5XSD4lF7nNuvrBju5hUeg9A6agRemgSXGl5YuE=",
        "encoding": "utf8"
      }
    }
  },
  {
    "email": "peter@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "hmac",
      "hash": {
        "value": "cg7f42jH39/2EaAU4wNd4s2lKIk=",
        "encoding": "base64",
        "digest": "sha1",
        "key": {
          "value": "736868",
          "encoding": "hex"
        }
      }
    }
  },
  {
    "email": "carmella@example.com",
    "email_verified": false,
    "custom_password_hash": {
      "algorithm": "scrypt",
      "hash": {
        "value": "097f6197e1b41538f723e32aa7a68e8d76227d8e432ce5faa4882a913032db29",
        "encoding": "hex"
      },
      "salt": {
        "value": "abc123",
        "encoding": "utf8"
      },
      "keylen": 32,
      "cost": 4096
    }
  }
]

MFA factors examples

Some examples of users with MFA factors:

[
  {
    "email": "antoinette@example.com",
    "mfa_factors": [
      {
        "totp": {
          "secret": "2PRXZWZAYYDAWCD"
        }
      },
      {
        "phone": {
          "value": "+15551112233"
        }
      },
      {
        "email": {
          "value": "antoinette@example.org"
        }
      }
    ]
  },
  {
    "email": "mary@example.com",
    "mfa_factors": [
      {
        "totp": {
          "secret": "JBTWY3DPEHPK3PNP"
        }
      }
    ]
  },
  {
    "email": "velma@example.com",
    "mfa_factors": [
      {
        "phone": {
          "value": "+15551234567"
        }
      },
    ]
  },
  {
  "email": "edward@example.com",
    "mfa_factors": [
      {
        "email": {
          "value": "edward@example.org"
        }
      }
    ]
  }
]

Concepts

How To

Reference

Use Cases

User Data JSON Schema for Bulk User Imports

User JSON schema

User object properties

User data JSON examples

​User JSON schema

​User object properties

​User data JSON examples

User JSON schema

User object properties

User data JSON examples