Users

The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.

The first name to assign to the user

The last name to assign to the user

Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the user's primary email address.

Phone numbers to add to the user. Must be unique across your instance. The first phone number will be set as the user's primary phone number.

Web3 wallets to add to the user. Must be unique across your instance. The first wallet will be set as the user's primary wallet.

The username to give to the user. It must be unique across your instance.

The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords.

In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. The digests should be generated with one of the supported algorithms. The hashing algorithm can be specified using the password_hasher property.

The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are bcrypt, bcrypt_sha256_django, bcrypt_peppered, hmac_sha256_utf16_b64, md5, pbkdf2_sha1, pbkdf2_sha256, pbkdf2_sha512, pbkdf2_sha256_django, phpass, scrypt_firebase, scrypt_werkzeug, sha256, sha256_salted and the argon2 variants argon2i and argon2id.

If you need support for any particular hashing algorithm, please let us know.

Note: for password hashers considered insecure (at this moment MD5 and SHA256), the corresponding user password hashes will be transparently migrated to Bcrypt (a secure hasher) upon the user's first successful password sign in. Insecure schemes are marked with (insecure) in the list below.

Each of the supported hashers expects the incoming digest to be in a particular format. Specifically:

bcrypt: The digest should be of the following form:

$<algorithm version>$<cost>$<salt & hash>

bcrypt_sha256_django: This is the Django-specific variant of Bcrypt, using SHA256 hashing function. The format should be as follows (as exported from Django):

bcrypt_sha256$$<algorithm version>$<cost>$<salt & hash>

bcrypt_peppered: As used in implementations such as Devise for Ruby on Rails applications. Identical to bcrypt except for the fact that a pepper string is appended to the input before hashing. Should be provided in the following format:

$<algorithm version>$<cost>$<salt & hash>$<pepper>

hmac_sha256_utf16_b64 (insecure): This is HMAC algorithm using the SHA256 hashing function. The format should be as follows:

hmac_sha256_utf16_b64$<hash>$<key>

md5 (insecure): The digest should follow the regular form e.g.:

5f4dcc3b5aa765d61d8327deb882cf99

pbkdf2_sha256: This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows:

pbkdf2_sha256$<iterations>$<salt>$<hash>

Note: Both the salt and the hash are expected to be base64-encoded.

pbkdf2_sha512: This is the PBKDF2 algorithm using the SHA512 hashing function. The format should be as follows:

pbkdf2_sha512$<iterations>$<salt>$<hash>

iterations: The number of iterations used. Must be an integer less than 420000. salt: The salt used when generating the hash. Must be less than 1024 bytes. hash: The hex-encoded hash. Must have been generated with a key length less than 1024 bytes.

pbkdf2_sha256_django: This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django):

pbkdf2_sha256$<iterations>$<salt>$<hash>

Note: The salt is expected to be un-encoded, the hash is expected base64-encoded.

pbkdf2_sha1: This is similar to pkbdf2_sha256_django, but with two differences:

1. uses sha1 instead of sha256
2. accepts the salt as a hex-encoded string. If the salt is not a valid hex string, the raw bytes will be used instead
3. accepts the hash as a hex-encoded string
4. optionally accepts the key length as the last parameter (defaults to 32)

The format is the following:

pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string> or pbkdf2_sha1$<iterations>$<salt-as-hex-string>$<hash-as-hex-string>$<key-length>

phpass: Portable public domain password hashing framework for use in PHP applications. Digests hashed with phpass have the following sections:

The format is the following:

$P$<rounds><salt><encoded-checksum>

• $P$ is the prefix used to identify phpass hashes.
• rounds is a single character encoding a 6-bit integer representing the number of rounds used.
• salt is eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt.
• checksum is 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.

scrypt_firebase: The Firebase-specific variant of scrypt. The value is expected to have 6 segments separated by the $ character and include the following information:

hash: The actual Base64 hash. This can be retrieved when exporting the user from Firebase. salt: The salt used to generate the above hash. Again, this is given when exporting the user. signer key: The base64 encoded signer key. salt separator: The base64 encoded salt separator. rounds: The number of rounds the algorithm needs to run. memory cost: The cost of the algorithm run

The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase. The other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.

Once you have all these, you can combine it in the following format and send this as the digest in order for Clerk to accept it:

<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>

scrypt_werkzeug: The Werkzeug-specific variant of scrypt.

The value is expected to have 3 segments separated by the $ character and include the following information:

algorithm args: The algorithm used to generate the hash. salt: The salt used to generate the above hash. hash: The actual Base64 hash.

The algorithm args are the parameters used to generate the hash and are included in the digest.

argon2i: Algorithms in the argon2 family generate digests that encode the following information:

version (v): The argon version, version 19 is assumed memory (m): The memory used by the algorithm (in kibibytes) iterations (t): The number of iterations to perform parallelism (p): The number of threads to use

Parts are demarcated by the $ character, with the first part identifying the algorithm variant. The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest.

$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc

argon2id: See the previous algorithm for an explanation of the formatting.

For the argon2id case, the value of the algorithm in the first part of the digest is argon2id:

$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU

sha256 (insecure): The digest should be a 64-length hex string, e.g.:

9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

sha256_salted (insecure): The digest should be a 64-length hex string with a salt.

The format is the following: <hash>$<salt>

The value is expected to have 2 segments separated by the $ character and include the following information: hash: The sha256 hash, a 64-length hex string. salt: The salt used to generate the above hash. Must be between 1 and 1024 bits.

awscognito:

This is a special migration hasher. The value must be awscognito.

When set, password_digest must be in the format of awscognito#<userpoolid>#<clientid>#<identifier>.

Upon a successful migration, password_hasher will be updated to bcrypt, and password_digest will be updated to a bcrypt hash.

See our migration guide for usage details.

When set to true all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password.

When set to true, password is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. Please note that you cannot use this flag if password is the only way for a user to sign into your instance.

In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Please note that currently the supported options are:

• Period: 30 seconds
• Code length: 6 digits
• Algorithm: SHA1

If Backup Codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest.

Metadata saved on the user, that is visible to both your Frontend and Backend APIs

Metadata saved on the user, that is only visible to your Backend API

Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.

If enabled, user can delete themselves via FAPI.

If enabled, user can create organizations via FAPI.

The maximum number of organizations the user can create. 0 means unlimited.

The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.

The first name to assign to the user

The last name to assign to the user

The ID of the email address to set as primary. It must be verified, and present on the current user.

If set to true, the user will be notified that their primary email address has changed. By default, no notification is sent.

The ID of the phone number to set as primary. It must be verified, and present on the current user.

The ID of the web3 wallets to set as primary. It must be verified, and present on the current user.

The username to give to the user. It must be unique across your instance.

The ID of the image to set as the user's profile image

The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords.

In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. The digests should be generated with one of the supported algorithms. The hashing algorithm can be specified using the password_hasher property.

The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are bcrypt, bcrypt_sha256_django, bcrypt_peppered, hmac_sha256_utf16_b64, md5, pbkdf2_sha1, pbkdf2_sha256, pbkdf2_sha512, pbkdf2_sha256_django, phpass, scrypt_firebase, scrypt_werkzeug, sha256, sha256_salted and the argon2 variants argon2i and argon2id.

If you need support for any particular hashing algorithm, please let us know.

Note: for password hashers considered insecure (at this moment MD5 and SHA256), the corresponding user password hashes will be transparently migrated to Bcrypt (a secure hasher) upon the user's first successful password sign in. Insecure schemes are marked with (insecure) in the list below.

Each of the supported hashers expects the incoming digest to be in a particular format. Specifically:

bcrypt: The digest should be of the following form:

$<algorithm version>$<cost>$<salt & hash>

bcrypt_sha256_django: This is the Django-specific variant of Bcrypt, using SHA256 hashing function. The format should be as follows (as exported from Django):

bcrypt_sha256$$<algorithm version>$<cost>$<salt & hash>

bcrypt_peppered: As used in implementations such as Devise for Ruby on Rails applications. Identical to bcrypt except for the fact that a pepper string is appended to the input before hashing. Should be provided in the following format:

$<algorithm version>$<cost>$<salt & hash>$<pepper>

hmac_sha256_utf16_b64 (insecure): This is HMAC algorithm using the SHA256 hashing function. The format should be as follows:

hmac_sha256_utf16_b64$<hash>$<key>

md5 (insecure): The digest should follow the regular form e.g.:

5f4dcc3b5aa765d61d8327deb882cf99

pbkdf2_sha256: This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows:

pbkdf2_sha256$<iterations>$<salt>$<hash>

Note: Both the salt and the hash are expected to be base64-encoded.

pbkdf2_sha512: This is the PBKDF2 algorithm using the SHA512 hashing function. The format should be as follows:

pbkdf2_sha512$<iterations>$<salt>$<hash>

iterations: The number of iterations used. Must be an integer less than 420000. salt: The salt used when generating the hash. Must be less than 1024 bytes. hash: The hex-encoded hash. Must have been generated with a key length less than 1024 bytes.

pbkdf2_sha256_django: This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django):

pbkdf2_sha256$<iterations>$<salt>$<hash>

Note: The salt is expected to be un-encoded, the hash is expected base64-encoded.

pbkdf2_sha1: This is similar to pkbdf2_sha256_django, but with two differences:

1. uses sha1 instead of sha256
2. accepts the salt as a hex-encoded string. If the salt is not a valid hex string, the raw bytes will be used instead
3. accepts the hash as a hex-encoded string
4. optionally accepts the key length as the last parameter (defaults to 32)

The format is the following:

pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string> or pbkdf2_sha1$<iterations>$<salt-as-hex-string>$<hash-as-hex-string>$<key-length>

phpass: Portable public domain password hashing framework for use in PHP applications. Digests hashed with phpass have the following sections:

The format is the following:

$P$<rounds><salt><encoded-checksum>

• $P$ is the prefix used to identify phpass hashes.
• rounds is a single character encoding a 6-bit integer representing the number of rounds used.
• salt is eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt.
• checksum is 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.

scrypt_firebase: The Firebase-specific variant of scrypt. The value is expected to have 6 segments separated by the $ character and include the following information:

hash: The actual Base64 hash. This can be retrieved when exporting the user from Firebase. salt: The salt used to generate the above hash. Again, this is given when exporting the user. signer key: The base64 encoded signer key. salt separator: The base64 encoded salt separator. rounds: The number of rounds the algorithm needs to run. memory cost: The cost of the algorithm run

The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase. The other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.

Once you have all these, you can combine it in the following format and send this as the digest in order for Clerk to accept it:

<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>

scrypt_werkzeug: The Werkzeug-specific variant of scrypt.

The value is expected to have 3 segments separated by the $ character and include the following information:

algorithm args: The algorithm used to generate the hash. salt: The salt used to generate the above hash. hash: The actual Base64 hash.

The algorithm args are the parameters used to generate the hash and are included in the digest.

argon2i: Algorithms in the argon2 family generate digests that encode the following information:

version (v): The argon version, version 19 is assumed memory (m): The memory used by the algorithm (in kibibytes) iterations (t): The number of iterations to perform parallelism (p): The number of threads to use

Parts are demarcated by the $ character, with the first part identifying the algorithm variant. The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest.

$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc

argon2id: See the previous algorithm for an explanation of the formatting.

For the argon2id case, the value of the algorithm in the first part of the digest is argon2id:

$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU

sha256 (insecure): The digest should be a 64-length hex string, e.g.:

9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

sha256_salted (insecure): The digest should be a 64-length hex string with a salt.

The format is the following: <hash>$<salt>

The value is expected to have 2 segments separated by the $ character and include the following information: hash: The sha256 hash, a 64-length hex string. salt: The salt used to generate the above hash. Must be between 1 and 1024 bits.

awscognito:

This is a special migration hasher. The value must be awscognito.

When set, password_digest must be in the format of awscognito#<userpoolid>#<clientid>#<identifier>.

Upon a successful migration, password_hasher will be updated to bcrypt, and password_digest will be updated to a bcrypt hash.

See our migration guide for usage details.

Set it to true if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a password.

Set to true to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a password.

In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it. Please note that currently the supported options are:

• Period: 30 seconds
• Code length: 6 digits
• Algorithm: SHA1

If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest.

Metadata saved on the user, that is visible to both your Frontend and Backend APIs

Metadata saved on the user, that is only visible to your Backend API

Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.

If true, the user can delete themselves with the Frontend API.

If true, the user can create organizations with the Frontend API.

The maximum number of organizations the user can create. 0 means unlimited.