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 >= 3 characters

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.

email_address_query
string >= 3 characters

Returns users with emails that match the given query, via case-insensitive partial match. For example, email_address_query=ello will match a user with the email HELLO@example.com.

phone_number_query
string >= 3 characters

Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, phone_number_query=555 will match a user with the phone number +1555xxxxxxx.

username_query
string >= 3 characters

Returns users with usernames that match the given query, via case-insensitive partial match. For example, username_query=CoolUser will match a user with the username SomeCoolUser.

name_query
string >= 3 characters

Returns users with names that match the given query, via case-insensitive partial match.

last_active_at_before
integer

Returns users whose last session activity was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.

Example: last_active_at_before=1700690400000
last_active_at_after
integer

Returns users whose last session activity was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.

Example: last_active_at_after=1700690400000
last_active_at_since
integer
Deprecated

Returns users that had session activity since the given date. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. Deprecated in favor of last_active_at_after.

Example: last_active_at_since=1700690400000
created_at_before
integer

Returns users who have been created before the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.

Example: created_at_before=1730160000000
created_at_after
integer

Returns users who have been created after the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.

Example: created_at_after=1730160000000
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.

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 by their created_at,updated_at,email_address,web3wallet,first_name,last_name,phone_number,username,last_active_at,last_sign_in_at. 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. We only support one order_by parameter, and if multiple order_by parameters are provided, we will only keep the first one. For example, if you pass order_by=username&order_by=created_at, we will consider only the first order_by parameter, which is username. The created_at parameter will be ignored in this case.

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
required
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 (PasswordHasher)

The hashing algorithm that was used to generate the password digest.

The algorithms we support at the moment are bcrypt, bcrypt_sha256_django, md5, pbkdf2_sha1, pbkdf2_sha256, pbkdf2_sha256_django, phpass, scrypt_firebase, scrypt_werkzeug, sha256, and the argon2 variants: argon2i and argon2id.

Each of the supported hashers expects the incoming digest to be in a particular format. See the Clerk docs for more information.

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.

object

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

object

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

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.

delete_self_enabled
boolean or null

If enabled, user can delete themselves via FAPI.

legal_accepted_at
string or null

A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

skip_legal_checks
boolean or null

When set to true all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.

create_organization_enabled
boolean or null

If enabled, user can create organizations via FAPI.

create_organizations_limit
integer or null

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

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

403

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": "string",
  • "skip_password_checks": true,
  • "skip_password_requirement": true,
  • "totp_secret": "string",
  • "backup_codes": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "delete_self_enabled": true,
  • "legal_accepted_at": "string",
  • "skip_legal_checks": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

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 >= 3 characters

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.

email_address_query
string >= 3 characters

Counts users with emails that match the given query, via case-insensitive partial match. For example, email_address_query=ello will match a user with the email HELLO@example.com, and will be included in the resulting count.

phone_number_query
string >= 3 characters

Counts users with phone numbers that match the given query, via case-insensitive partial match. For example, phone_number_query=555 will match a user with the phone number +1555xxxxxxx, and will be included in the resulting count.

username_query
string >= 3 characters

Counts users with usernames that match the given query, via case-insensitive partial match. For example, username_query=CoolUser will match a user with the username SomeCoolUser, and will be included in the resulting count.

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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

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.

This endpoint allows changing a user's password. When passing the password parameter directly you have two further options. You can ignore the password policy checks for your instance by setting the skip_password_checks parameter to true. You can also choose to sign the user out of all their active sessions on any device once the password is updated. Just set sign_out_of_other_sessions to true.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to update

Request Body schema: application/json
required
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.

notify_primary_email_address_changed
boolean
Default: false

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

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.

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 (PasswordHasher)

The hashing algorithm that was used to generate the password digest.

The algorithms we support at the moment are bcrypt, bcrypt_sha256_django, md5, pbkdf2_sha1, pbkdf2_sha256, pbkdf2_sha256_django, phpass, scrypt_firebase, scrypt_werkzeug, sha256, and the argon2 variants: argon2i and argon2id.

Each of the supported hashers expects the incoming digest to be in a particular format. See the Clerk docs for more information.

skip_password_checks
boolean or null

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.

sign_out_of_other_sessions
boolean or null

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.

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.

object

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

object

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

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.

delete_self_enabled
boolean or null

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

create_organization_enabled
boolean or null

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

legal_accepted_at
string or null

A custom timestamps denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

skip_legal_checks
boolean or null

When set to true all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.

create_organizations_limit
integer or null

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

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",
  • "notify_primary_email_address_changed": false,
  • "primary_phone_number_id": "string",
  • "primary_web3_wallet_id": "string",
  • "username": "string",
  • "profile_image_id": "string",
  • "password": "string",
  • "password_digest": "string",
  • "password_hasher": "string",
  • "skip_password_checks": true,
  • "sign_out_of_other_sessions": true,
  • "totp_secret": "string",
  • "backup_codes": [
    ],
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "legal_accepted_at": "string",
  • "skip_legal_checks": true,
  • "create_organizations_limit": 0,
  • "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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

Lock a user

Marks the given user as locked, which means they are not allowed to sign in again until the lock expires. Lock duration can be configured in the instance's restrictions settings.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to lock

Responses
200

Success

403

Authorization invalid

post/users/{user_id}/lock
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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

Unlock a user

Removes the lock from the given user.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to unlock

Responses
200

Success

403

Authorization invalid

post/users/{user_id}/unlock
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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

Set user profile image

Update a user's profile image

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to update the profile image for

Request Body schema: multipart/form-data
required
file
string <binary>
Responses
200

Success

400

Request was not successful

401

Request was not successful

404

Request was not successful

post/users/{user_id}/profile_image
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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

Delete user profile image

Delete a user's profile image

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user to delete the profile image for

Responses
200

Success

404

Request was not successful

delete/users/{user_id}/profile_image
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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

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
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.

object

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

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",
  • "image_url": "string",
  • "has_image": true,
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { },
  • "email_addresses": [
    ],
  • "phone_numbers": [
    ],
  • "web3_wallets": [
    ],
  • "passkeys": [
    ],
  • "password_enabled": true,
  • "two_factor_enabled": true,
  • "totp_enabled": true,
  • "backup_code_enabled": true,
  • "mfa_enabled_at": 0,
  • "mfa_disabled_at": 0,
  • "external_accounts": [
    ],
  • "saml_accounts": [
    ],
  • "last_sign_in_at": 0,
  • "banned": true,
  • "locked": true,
  • "lockout_expires_in_seconds": 0,
  • "verification_attempts_remaining": 0,
  • "updated_at": 0,
  • "created_at": 0,
  • "delete_self_enabled": true,
  • "create_organization_enabled": true,
  • "create_organizations_limit": 0,
  • "last_active_at": 1700690400000,
  • "legal_accepted_at": 1700690400000
}

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.

400

Request was not successful

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.

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
}

Retrieve all invitations for a user

Retrieve a paginated list of the user's organization invitations

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user whose organization invitations 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.

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.

status
string

Filter organization invitations based on their status

Enum: "pending" "accepted" "revoked"
Responses
200

A list of organization invitations with public organization data

400

Request was not successful

403

Request was not successful

404

Resource not found

get/users/{user_id}/organization_invitations
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"
}

Disable all user's Backup codes

Disable all of a user's backup codes.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user whose backup codes are to be deleted.

Responses
200

Successful operation.

404

Resource not found

500

Request was not successful

delete/users/{user_id}/backup_code
Response samples
application/json
{
  • "user_id": "string"
}

Delete a user passkey

Delete the passkey identification for a given user and notify them through email.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user that owns the passkey identity

passkey_identification_id
required
string

The ID of the passkey identity to be deleted

Responses
200

Deleted Object

403

Authorization invalid

404

Resource not found

500

Request was not successful

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

Delete a user web3 wallet

Delete the web3 wallet identification for a given user.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user that owns the web3 wallet

web3_wallet_identification_id
required
string

The ID of the web3 wallet identity to be deleted

Responses
200

Deleted Object

400

Request was not successful

403

Authorization invalid

404

Resource not found

500

Request was not successful

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

Create a TOTP for a user

Creates a TOTP (Time-based One-Time Password) for a given user, returning both the TOTP secret and the URI.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user for whom the TOTP is being created.

Responses
200

A TOTP (Time-based One-Time Password)

403

Request was not successful

404

Resource not found

500

Request was not successful

post/users/{user_id}/totp
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "secret": "string",
  • "uri": "string",
  • "verified": true,
  • "backup_codes": [
    ]
}

Delete all the user's TOTPs

Deletes all of the user's TOTPs.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user whose TOTPs are to be deleted

Responses
200

Successful operation.

404

Resource not found

500

Request was not successful

delete/users/{user_id}/totp
Response samples
application/json
{
  • "user_id": "string"
}

Delete External Account

Delete an external account by ID.

SecuritybearerAuth
Request
path Parameters
user_id
required
string

The ID of the user's external account

external_account_id
required
string

The ID of the external account to delete

Responses
200

Deleted Object

400

Request was not successful

403

Request was not successful

404

Resource not found

500

Request was not successful

delete/users/{user_id}/external_accounts/{external_account_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}
➔ Next to Webhooks