Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth-test.auth0-mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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."
    },
    "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

​
app_metadata
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.
​
blocked
boolean
Whether the user has been blocked.
​
email
string
required
The user’s email address.
​
email_verified
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.
​
family_name
string
upsertable
The user’s family name.
​
given_name
string
upsertable
The user’s given name.
​
name
string
upsertable
The user’s full name.
​
nickname
string
upsertable
The user’s nickname.
​
picture
string
upsertable
URL pointing to the user’s profile picture.
​
user_id
string
The user’s unique identifier. This is prepended by the connection strategy.
​
user_metadata
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.
​
username
string
The user’s username.
​
password_hash
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.
​
custom_password_hash
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.
​
mfa_factors
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.

​
User data JSON examples

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"
    }
  }
]
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
    }
  }
]
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"
        }
      }
    ]
  }
]