Clerk docs

Users

The user object represents a user that has successfully signed up to your application.

https://clerk.com/docs/reference/clerkjs/user

List all users

Returns a list of all users. The users are returned sorted by creation date, with the newest users appearing first.

SecuritybearerAuth
Request
query Parameters
email_address
Array of strings

Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.

phone_number
Array of strings

Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.

external_id
Array of strings

Returns users with the specified external ids. For each external id, the + and - can be prepended to the id, which denote whether the respective external id should be included or excluded from the result set. Accepts up to 100 external ids. Any external ids not found are ignored.

username
Array of strings

Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.

web3_wallet
Array of strings

Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored.

user_id
Array of strings

Returns users with the user ids specified. For each user id, the + and - can be prepended to the id, which denote whether the respective user id should be included or excluded from the result set. Accepts up to 100 user ids. Any user ids not found are ignored.

organization_id
Array of strings

Returns users that have memberships to the given organizations. For each organization id, the + and - can be prepended to the id, which denote whether the respective organization should be included or excluded from the result set. Accepts up to 100 organization ids.

query
string

Returns users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well.

limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset. Must be an integer greater than zero and less than 500. By default, if not supplied, a limit of 10 is used.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

order_by
string
Default: "-created_at"

Allows to return users in a particular order. At the moment, you can order the returned users either by their created_at or updated_at timestamp. In order to specify the direction, you can use the +/- symbols prepended in the property to order by. For example, if you want users to be returned in descending order according to their created_at property, you can use -created_at. If you don't use + or -, then + is implied. Defaults to -created_at.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

422

Invalid request parameters

get/users
Response samples
application/json
[
  • {
    }
]

Create a new user

Creates a new user. Your user management settings determine how you should setup your user model.

Any email address and phone number created using this method will be marked as verified.

Note: If you are performing a migration, check out our guide on zero downtime migrations.

A rate limit rule of 20 requests per 10 seconds is applied to this endpoint.

SecuritybearerAuth
Request
Request Body schema: application/json
external_id
string or null

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

first_name
string or null

The first name to assign to the user

last_name
string or null

The last name to assign to the user

email_address
Array of strings

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_number
Array of strings

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_wallet
Array of strings

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.

username
string or null

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

password
string or null

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

password_digest
string

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.

password_hasher
string

The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are bcrypt, md5, pbkdf2_sha256, pbkdf2_sha256_django, scrypt_firebase and 2 argon2 variants, argon2i and argon2id. Each of the above expects the incoming digest to be of a particular format.

More specifically:

bcrypt: The digest should be of the following form:

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

md5: 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_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 hash as a hex-encoded string

The format is the following:

pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string>

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>

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

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

Enum: "bcrypt" "md5" "pbkdf2_sha256" "pbkdf2_sha256_django" "pbkdf2_sha1" "scrypt_firebase" "argon2i" "argon2id"
skip_password_checks
boolean

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.

skip_password_requirement
boolean

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.

totp_secret
string

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
backup_codes
Array of strings

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.

public_metadata
object

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

private_metadata
object

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

unsafe_metadata
object

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.

created_at
string

A custom date/time denoting when the user signed up to the application, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

Responses
200

Success

400

Request was not successful

401

Authentication invalid

422

Invalid request parameters

post/users
Request samples
application/json
{
  • "external_id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email_address": [
    ],
  • "phone_number": [
    ],
  • "web3_wallet": [
    ],
  • "username": "string",
  • "password": "string",
  • "password_digest": "string",
  • "password_hasher": "bcrypt",
  • "skip_password_checks": true,
  • "skip_password_requirement": true,
  • "totp_secret": "string",
  • "backup_codes": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "created_at": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "user",
  • "external_id": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "profile_image_url": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "gender": "string",
  • "birthday": "string",
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "external_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "updated_at": 0,
  • "created_at": 0
}

Count users

Returns a total count of all users that match the given filtering criteria.

SecuritybearerAuth
Request
query Parameters
email_address
Array of strings

Counts users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.

phone_number
Array of strings

Counts users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.

external_id
Array of strings

Counts users with the specified external ids. Accepts up to 100 external ids. Any external ids not found are ignored.

username
Array of strings

Counts users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.

web3_wallet
Array of strings

Counts users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored.

user_id
Array of strings

Counts users with the user ids specified. Accepts up to 100 user ids. Any user ids not found are ignored.

query
string

Counts users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well.

Responses
200

Success

422

Invalid request parameters

get/users/count
Response samples
application/json
{
  • "object": "total_count",
  • "total_count": 0
}

Retrieve a user

Retrieve the details of a user

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to retrieve

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

get/users/{user_id}
Response samples
application/json
{
  • "id": "string",
  • "object": "user",
  • "external_id": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "profile_image_url": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "gender": "string",
  • "birthday": "string",
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "external_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "updated_at": 0,
  • "created_at": 0
}

Update a user

Update a user's attributes.

You can set the user's primary contact identifiers (email address and phone numbers) by updating the primary_email_address_id and primary_phone_number_id attributes respectively. Both IDs should correspond to verified identifications that belong to the user.

You can remove a user's username by setting the username attribute to null or the blank string "". This is a destructive action; the identification will be deleted forever. Usernames can be removed only if they are optional in your instance settings and there's at least one other identifier which can be used for authentication.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to update

Request Body schema: application/json
external_id
string or null

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

first_name
string or null

The first name to assign to the user

last_name
string or null

The last name to assign to the user

primary_email_address_id
string

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

primary_phone_number_id
string

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

primary_web3_wallet_id
string

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

username
string or null

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

profile_image_id
string or null

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

password
string or null

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

totp_secret
string

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
backup_codes
Array of strings

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.

public_metadata
object

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

private_metadata
object

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

unsafe_metadata
object

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.

created_at
string

A custom date/time denoting when the user signed up to the application, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

422

Invalid request parameters

patch/users/{user_id}
Request samples
application/json
{
  • "external_id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "profile_image_id": "string",
  • "password": "string",
  • "totp_secret": "string",
  • "backup_codes": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "created_at": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "user",
  • "external_id": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "profile_image_url": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "gender": "string",
  • "birthday": "string",
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "external_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "updated_at": 0,
  • "created_at": 0
}

Delete a user

Delete the specified user

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to delete

Responses
200

Deleted Object

400

Request was not successful

401

Authentication invalid

404

Resource not found

delete/users/{user_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}

Ban a user

Marks the given user as banned, which means that all their sessions are revoked and they are not allowed to sign in again.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to ban

Responses
200

Success

402

Payment required

post/users/{user_id}/ban
Response samples
application/json
{
  • "id": "string",
  • "object": "user",
  • "external_id": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "profile_image_url": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "gender": "string",
  • "birthday": "string",
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "external_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "updated_at": 0,
  • "created_at": 0
}

Unban a user

Removes the ban mark from the given user.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to unban

Responses
200

Success

402

Payment required

post/users/{user_id}/unban
Response samples
application/json
{
  • "id": "string",
  • "object": "user",
  • "external_id": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "profile_image_url": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "gender": "string",
  • "birthday": "string",
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "external_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "updated_at": 0,
  • "created_at": 0
}

Merge and update a user's metadata

Update a user's metadata attributes by merging existing values with the provided parameters.

This endpoint behaves differently than the Update a user endpoint. Metadata values will not be replaced entirely. Instead, a deep merge will be performed. Deep means that any nested JSON objects will be merged as well.

You can remove metadata keys at any level by setting their value to null.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user whose metadata will be updated and merged

Request Body schema: application/json
public_metadata
object

Metadata saved on the user, that is visible to both your frontend and backend. The new object will be merged with the existing value.

private_metadata
object

Metadata saved on the user that is only visible to your backend. The new object will be merged with the existing value.

unsafe_metadata
object

Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. The new object will be merged with the existing value.

Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

422

Invalid request parameters

patch/users/{user_id}/metadata
Request samples
application/json
{
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { }
}
Response samples
application/json
{
  • "id": "string",
  • "object": "user",
  • "external_id": "string",
  • "primary_email_address_id": "string",
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "profile_image_url": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "gender": "string",
  • "birthday": "string",
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "external_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "updated_at": 0,
  • "created_at": 0
}

Retrieve the OAuth access token of a user

Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider. For OAuth 2.0, if the access token has expired and we have a corresponding refresh token, the access token will be refreshed transparently the new one will be returned.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user for which to retrieve the OAuth access token

provider
required
string

The ID of the OAuth provider (e.g. oauth_google)

Responses
200

The OAuth access token of the user, if any.

422

Invalid request parameters

get/users/{user_id}/oauth_access_tokens/{provider}
Response samples
application/json
[
  • {
    }
]

Retrieve all memberships for a user

Retrieve a paginated list of the user's organization memberships

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user whose organization memberships we want to retrieve

query Parameters
limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset. Must be an integer greater than zero and less than 500. By default, if not supplied, a limit of 10 is used.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

Responses
200

A list of organization memberships

403

Request was not successful

get/users/{user_id}/organization_memberships
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Verify the password of a user

Check that the user's password matches the supplied input. Useful for custom auth flows and re-verification.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user for whom to verify the password

Request Body schema: application/json
password
required
string

The user password to verify

Responses
200

The provided password was correct.

400

The user does not have a password set.

404

The user does not exist.

422

The provided password was incorrect.

500

Request was not successful

post/users/{user_id}/verify_password
Request samples
application/json
{
  • "password": "string"
}
Response samples
application/json
{
  • "verified": true
}

Verify a TOTP or backup code for a user

Verify that the provided TOTP or backup code is valid for the user. Verifying a backup code will result it in being consumed (i.e. it will become invalid). Useful for custom auth flows and re-verification.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user for whom to verify the TOTP

Request Body schema: application/json
code
required
string

The TOTP or backup code to verify

Responses
200

The provided TOTP or backup code was correct.

400

The user does not have TOTP configured for their account.

404

The user does not exist.

422

The provided TOTP or backup code was incorrect.

500

Request was not successful

post/users/{user_id}/verify_totp
Request samples
application/json
{
  • "code": "string"
}
Response samples
application/json
{
  • "verified": true,
  • "code_type": "totp"
}

Disable a user's MFA methods

Disable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP on their authenticator app) at once.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user whose MFA methods are to be disabled

Responses
200

Successful operation.

404

Resource not found

500

Request was not successful

delete/users/{user_id}/mfa
Response samples
application/json
{
  • "user_id": "string"
}
➔ Next to Webhooks