README.md

Users

Overview

Available Operations

• list - List all users
• create - Create a new user
• count - Count users
• get - Retrieve a user
• update - Update a user
• delete - Delete a user
• ban - Ban a user
• unban - Unban a user
• bulk_ban - Ban multiple users
• bulk_unban - Unban multiple users
• lock - Lock a user
• unlock - Unlock a user
• set_profile_image - Set user profile image
• delete_profile_image - Delete user profile image
• update_metadata - Merge and update a user's metadata
• replace_metadata - Replace a user's metadata
• get_billing_subscription - Retrieve a user's billing subscription
• get_billing_credit_balance - Retrieve a user's credit balance
• adjust_billing_credit_balance - Adjust a user's credit balance
• get_o_auth_access_token - Retrieve the OAuth access token of a user
• get_organization_memberships - Retrieve all memberships for a user
• get_organization_invitations - Retrieve all invitations for a user
• remove_password - Remove a user's password
• verify_password - Verify the password of a user
• verify_totp - Verify a TOTP or backup code for a user
• disable_mfa - Disable a user's MFA methods
• delete_backup_codes - Disable all user's Backup codes
• delete_passkey - Delete a user passkey
• list_trusted_devices - List a user's trusted devices
• revoke_trusted_device - Revoke a user's trusted device
• delete_web3_wallet - Delete a user web3 wallet
• delete_totp - Delete all the user's TOTPs
• delete_external_account - Delete External Account
• set_password_compromised - Set a user's password as compromised
• unset_password_compromised - Unset a user's password as compromised
• get_instance_organization_memberships - Get a list of all organization memberships within an instance.

list

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.list(request={
        "email_address": [
            "test@example.com",
        ],
        "phone_number": [
            "+12345678901",
        ],
        "external_id": [
            "external-id-123",
        ],
        "username": [
            "user123",
        ],
        "web3_wallet": [
            "0x123456789abcdef0x123456789abcdef",
        ],
        "user_id": [
            "user-id-123",
        ],
        "organization_id": [
            "org-id-123",
        ],
        "query": "John",
        "email_address_query": "<value>",
        "phone_number_query": "<value>",
        "username_query": "<value>",
        "name_query": "<value>",
        "banned": True,
        "last_active_at_before": 1700690400000,
        "last_active_at_after": 1700690400000,
        "last_active_at_since": 1700690400000,
        "created_at_before": 1730160000000,
        "created_at_after": 1730160000000,
        "last_sign_in_at_before": 1700690400000,
        "last_sign_in_at_after": 1700690400000,
        "provider": "<value>",
        "provider_user_id": [
            "<id 1>",
        ],
        "limit": 20,
        "offset": 10,
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
request	models.GetUserListRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

List[models.User]

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 422	application/json
models.SDKError	4XX, 5XX	*/*

create

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

By default, any email address and phone number created using this method is marked as verified. Use the email_address_identification_status and phone_number_identification_status arrays to instead create some or all of them as reserved (unverified but usable for sign-in and locked so no other user can claim them).

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

The following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instances

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.create(external_id="ext-id-001", first_name="John", last_name="Doe", locale="en", email_address=[
        "john.doe@example.com",
    ], email_address_identification_status=[
        clerk_backend_api.EmailAddressIdentificationStatus.RESERVED,
    ], phone_number=[
        "+12345678901",
    ], phone_number_identification_status=[
        clerk_backend_api.PhoneNumberIdentificationStatus.VERIFIED,
    ], web3_wallet=[
        "0x123456789abcdef0x123456789abcdef",
    ], username="johndoe123", password="Secure*Pass4", password_digest="$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc", password_hasher="<value>", skip_password_checks=False, skip_password_requirement=False, totp_secret="base32totpsecretkey", backup_codes=[
        "123456",
        "654321",
    ], public_metadata={
        "role": "user",
    }, private_metadata={
        "internal_id": "789",
    }, unsafe_metadata={
        "preferences": {
            "theme": "dark",
        },
    }, delete_self_enabled=True, legal_accepted_at="<value>", skip_legal_checks=False, skip_user_requirement=True, create_organization_enabled=None, create_organizations_limit=81560, created_at="2023-03-15T07:15:20.902Z", bypass_client_trust=True, banned=True, locked=False)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
external_id	OptionalNullable[str]	➖	The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.	ext-id-001
first_name	OptionalNullable[str]	➖	The first name to assign to the user	John
last_name	OptionalNullable[str]	➖	The last name to assign to the user	Doe
locale	OptionalNullable[str]	➖	The locale to assign to the user (e.g., "en-US", "fr-FR")
email_address	List[str]	➖	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. Created verified by default; see email_address_identification_status to create them reserved.
email_address_identification_status	List[models.EmailAddressIdentificationStatus]	➖	Controls the status each email address is created with. Runs parallel to email_address: when provided, it must contain exactly one item per email address, applied by position. When omitted or empty, every email address is created verified. Set an item to reserved to create the corresponding email address reserved instead (unverified but usable for sign-in and locked so no other user can claim it).
phone_number	List[str]	➖	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. Created verified by default; see phone_number_identification_status to create them reserved.
phone_number_identification_status	List[models.PhoneNumberIdentificationStatus]	➖	Controls the status each phone number is created with. Runs parallel to phone_number: when provided, it must contain exactly one item per phone number, applied by position. When omitted or empty, every phone number is created verified. Set an item to reserved to create the corresponding phone number reserved instead (unverified but usable for sign-in and locked so no other user can claim it).
web3_wallet	List[str]	➖	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	OptionalNullable[str]	➖	The username to give to the user. It must be unique across your instance.	johndoe123
password	OptionalNullable[str]	➖	The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords.	Secure*Pass4
password_digest	OptionalNullable[str]	➖	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.	$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc
password_hasher	Optional[str]	➖	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, pbkdf2_sha512, phpass, md5_phpass, scrypt_firebase, scrypt_werkzeug, sha256, ldap_ssha, the argon2 variants: argon2i and argon2id, sha512_symfony, the SHA-512 variant of the Symfony legacy hasher, and pbkdf2_sha512_hex, a variant of pbkdf2_sha512 that accepts hex-encoded salt and hash. 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	OptionalNullable[bool]	➖	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.	false
skip_password_requirement	OptionalNullable[bool]	➖	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.	false
totp_secret	OptionalNullable[str]	➖	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	base32totpsecretkey
backup_codes	List[str]	➖	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.	[ "123456", "654321" ]
public_metadata	Dict[str, Any]	➖	Metadata saved on the user, that is visible to both your Frontend and Backend APIs	{ "role": "user" }
private_metadata	Dict[str, Any]	➖	Metadata saved on the user, that is only visible to your Backend API	{ "internal_id": "789" }
unsafe_metadata	Dict[str, Any]	➖	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.	{ "preferences": { "theme": "dark" } }
delete_self_enabled	OptionalNullable[bool]	➖	If enabled, user can delete themselves via FAPI.
legal_accepted_at	OptionalNullable[str]	➖	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	OptionalNullable[bool]	➖	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.
skip_user_requirement	OptionalNullable[bool]	➖	When set to true, identification types are not enforced. At least one identification type must be enabled and provided on your instance (email, phone, web3 wallet, or username). Users created without required identification types cannot use those authentication strategies It is not recommended to use this flag unless you need to allow Clerk UI components to prompt for required fields while BAPI creates users with minimal data, or for migration a user to Clerk.
create_organization_enabled	OptionalNullable[bool]	➖	If enabled, user can create organizations via FAPI.
create_organizations_limit	OptionalNullable[int]	➖	The maximum number of organizations the user can create. 0 means unlimited.
created_at	OptionalNullable[str]	➖	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).	2023-03-15T07:15:20.902Z
bypass_client_trust	OptionalNullable[bool]	➖	When set to true, the user will bypass client trust checks during sign-in.
banned	OptionalNullable[bool]	➖	When set to true, the user is created already banned and cannot sign in. Requires the same plan support as the ban user endpoint.
locked	OptionalNullable[bool]	➖	When set to true, the user is created already locked. Requires the user lockout feature to be enabled on the instance.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 402, 403, 422	application/json
models.SDKError	4XX, 5XX	*/*

count

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.count(request={
        "email_address": [
            "user@example.com",
        ],
        "phone_number": [
            "+1234567890",
        ],
        "external_id": [
            "external-id-123",
        ],
        "username": [
            "username123",
        ],
        "web3_wallet": [
            "0x123456789abcdef",
        ],
        "user_id": [
            "user-id-123",
        ],
        "organization_id": [
            "John Doe",
        ],
        "query": "<value>",
        "email_address_query": "<value>",
        "phone_number_query": "<value>",
        "username_query": "<value>",
        "name_query": "<value>",
        "banned": True,
        "last_active_at_before": 1700690400000,
        "last_active_at_after": 1700690400000,
        "last_active_at_since": 1700690400000,
        "created_at_before": 1730160000000,
        "created_at_after": 1730160000000,
        "last_sign_in_at_before": 1700690400000,
        "last_sign_in_at_after": 1700690400000,
        "provider": "<value>",
        "provider_user_id": [
            "<id 1>",
            "<id 2>",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
request	models.GetUsersCountRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.TotalCount

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	422	application/json
models.SDKError	4XX, 5XX	*/*

get

Retrieve the details of a user

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get(user_id="usr_1")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to retrieve	usr_1
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404	application/json
models.SDKError	4XX, 5XX	*/*

update

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

As of API version 2026-05-12, this endpoint no longer accepts public_metadata, private_metadata, or unsafe_metadata. Use PATCH /v1/users/{user_id}/metadata to merge updates into existing metadata, or PUT /v1/users/{user_id}/metadata to replace a metadata field entirely.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.update(user_id="usr_1", external_id="ext_123", first_name="Jane", last_name="Doe", locale="nl", primary_email_address_id="eml_12345", notify_primary_email_address_changed=True, primary_phone_number_id="phn_67890", primary_web3_wallet_id="wlt_123", username="janedoe", profile_image_id="img_789", password="secretPass123!", password_digest="$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc", password_hasher="<value>", skip_password_checks=False, sign_out_of_other_sessions=True, totp_secret="ABCD1234EFGH5678", backup_codes=[
        "123456",
        "654321",
    ], delete_self_enabled=True, create_organization_enabled=False, legal_accepted_at="<value>", skip_legal_checks=False, create_organizations_limit=824457, created_at="2021-04-05T14:30:00.000Z", bypass_client_trust=False)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to update	usr_1
external_id	OptionalNullable[str]	➖	The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.	ext_123
first_name	OptionalNullable[str]	➖	The first name to assign to the user	Jane
last_name	OptionalNullable[str]	➖	The last name to assign to the user	Doe
locale	OptionalNullable[str]	➖	The locale to assign to the user (e.g., "en-US", "fr-FR")
primary_email_address_id	OptionalNullable[str]	➖	The ID of the email address to set as primary. It must be verified, and present on the current user.	eml_12345
notify_primary_email_address_changed	OptionalNullable[bool]	➖	If set to true, the user will be notified that their primary email address has changed. By default, no notification is sent.	true
primary_phone_number_id	OptionalNullable[str]	➖	The ID of the phone number to set as primary. It must be verified, and present on the current user.	phn_67890
primary_web3_wallet_id	OptionalNullable[str]	➖	The ID of the web3 wallets to set as primary. It must be verified, and present on the current user.	wlt_123
username	OptionalNullable[str]	➖	The username to give to the user. It must be unique across your instance.	janedoe
profile_image_id	OptionalNullable[str]	➖	The ID of the image to set as the user's profile image	img_789
password	OptionalNullable[str]	➖	The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords.	secretPass123!
password_digest	Optional[str]	➖	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.	$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc
password_hasher	Optional[str]	➖	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, pbkdf2_sha512, phpass, md5_phpass, scrypt_firebase, scrypt_werkzeug, sha256, ldap_ssha, the argon2 variants: argon2i and argon2id, sha512_symfony, the SHA-512 variant of the Symfony legacy hasher, and pbkdf2_sha512_hex, a variant of pbkdf2_sha512 that accepts hex-encoded salt and hash. 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	OptionalNullable[bool]	➖	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.	false
sign_out_of_other_sessions	OptionalNullable[bool]	➖	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.	true
totp_secret	OptionalNullable[str]	➖	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.	ABCD1234EFGH5678
backup_codes	List[str]	➖	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.	[ "123456", "654321" ]
delete_self_enabled	OptionalNullable[bool]	➖	If true, the user can delete themselves with the Frontend API.	true
create_organization_enabled	OptionalNullable[bool]	➖	If true, the user can create organizations with the Frontend API.	false
legal_accepted_at	OptionalNullable[str]	➖	A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format.
skip_legal_checks	OptionalNullable[bool]	➖	When set to true all legal checks are skipped.
create_organizations_limit	OptionalNullable[int]	➖	The maximum number of organizations the user can create. 0 means unlimited.
created_at	OptionalNullable[str]	➖	A custom date/time denoting when the user signed up to the application.	2021-04-05T14:30:00.000Z
bypass_client_trust	OptionalNullable[bool]	➖	When set to true, the user will bypass client trust checks during sign-in.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 409, 422	application/json
models.SDKError	4XX, 5XX	*/*

delete

Delete the specified user

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete(user_id="usr_1")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to delete	usr_1
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeletedObject

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404	application/json
models.SDKError	4XX, 5XX	*/*

ban

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.ban(user_id="user_12345")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to ban	user_12345
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	402	application/json
models.SDKError	4XX, 5XX	*/*

unban

Removes the ban mark from the given user.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.unban(user_id="user_12345")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to unban	user_12345
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	402	application/json
models.SDKError	4XX, 5XX	*/*

bulk_ban

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.bulk_ban(user_ids=[
        "<value 1>",
        "<value 2>",
        "<value 3>",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_ids	List[str]	✔️	Array of user IDs to ban
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

List[models.User]

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 402	application/json
models.SDKError	4XX, 5XX	*/*

bulk_unban

Removes the ban mark from multiple users.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.bulk_unban(user_ids=[
        "<value 1>",
        "<value 2>",
        "<value 3>",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_ids	List[str]	✔️	Array of user IDs to unban
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

List[models.User]

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 402	application/json
models.SDKError	4XX, 5XX	*/*

lock

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.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.lock(user_id="user_123456789")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to lock	user_123456789
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403	application/json
models.SDKError	4XX, 5XX	*/*

unlock

Removes the lock from the given user.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.unlock(user_id="user_12345")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to unlock	user_12345
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403	application/json
models.SDKError	4XX, 5XX	*/*

set_profile_image

Update a user's profile image

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.set_profile_image(user_id="usr_test123", file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to update the profile image for	usr_test123
file	Optional[models.File]	➖	N/A
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404	application/json
models.SDKError	4XX, 5XX	*/*

delete_profile_image

Delete a user's profile image

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete_profile_image(user_id="usr_test123")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user to delete the profile image for	usr_test123
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	404	application/json
models.SDKError	4XX, 5XX	*/*

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.update_metadata(user_id="user_123456789", public_metadata={
        "key": "<value>",
    }, private_metadata={
        "key": "<value>",
        "key1": "<value>",
    }, unsafe_metadata={
        "key": "<value>",
        "key1": "<value>",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user whose metadata will be updated and merged	user_123456789
public_metadata	Dict[str, Any]	➖	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	Dict[str, Any]	➖	Metadata saved on the user that is only visible to your backend. The new object will be merged with the existing value.
unsafe_metadata	Dict[str, Any]	➖	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.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.SDKError	4XX, 5XX	*/*

replace_metadata

Replace a user's metadata attributes with the provided values.

Unlike PATCH /v1/users/{user_id}/metadata (merge semantics), this endpoint replaces the supplied metadata fields entirely — the prior contents of each supplied field are discarded. Fields omitted from the request body are left unchanged.

Prefer the PATCH endpoint for partial updates. Use PUT only when you explicitly intend to overwrite a metadata field wholesale.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.replace_metadata(user_id="<id>", public_metadata={
        "key": "<value>",
        "key1": "<value>",
        "key2": "<value>",
    }, private_metadata={
        "key": "<value>",
        "key1": "<value>",
        "key2": "<value>",
    }, unsafe_metadata={
        "key": "<value>",
        "key1": "<value>",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose metadata will be replaced
public_metadata	Dict[str, Any]	➖	Metadata saved on the user, that is visible to both your frontend and backend. The existing value will be replaced entirely with the new object.
private_metadata	Dict[str, Any]	➖	Metadata saved on the user that is only visible to your backend. The existing value will be replaced entirely with the new object.
unsafe_metadata	Dict[str, Any]	➖	Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. The existing value will be replaced entirely with the new object. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 404, 422	application/json
models.SDKError	4XX, 5XX	*/*

get_billing_subscription

Retrieves the billing subscription for the specified user. This includes subscription details, active plans, billing information, and payment status. The subscription contains subscription items which represent the individual plans the user is subscribed to.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get_billing_subscription(user_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose subscription to retrieve
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CommerceSubscription

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

get_billing_credit_balance

Retrieves the current credit balance for the specified user. Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get_billing_credit_balance(user_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose credit balance to retrieve
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CommerceCreditBalanceResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

adjust_billing_credit_balance

Increases or decreases the credit balance for the specified user. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures that duplicate requests are safely handled.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.adjust_billing_credit_balance(user_id="<id>", amount=562473, action=clerk_backend_api.Action.DECREASE, idempotency_key="<value>", currency="New Israeli Sheqel", note="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose credit balance to adjust
amount	int	✔️	The credit amount in cents. Must be greater than zero.
action	models.Action	✔️	Whether to increase or decrease the credit balance.
idempotency_key	str	✔️	A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry.
currency	Optional[str]	➖	The currency code (e.g. "USD"). Defaults to USD if not provided.
note	Optional[str]	➖	An optional note to attach to the ledger entry.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CommerceCreditLedgerResponse

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 409, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

get_o_auth_access_token

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.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get_o_auth_access_token(user_id="user_123", provider="oauth_google", paginated=True, limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user for which to retrieve the OAuth access token	user_123
provider	str	✔️	The ID of the OAuth provider (e.g. oauth_google)	oauth_google
paginated	Optional[bool]	➖	Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
limit	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with offset.	20
offset	Optional[int]	➖	Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.	10
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

List[models.OAuthAccessToken]

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 404, 422	application/json
models.SDKError	4XX, 5XX	*/*

get_organization_memberships

Retrieve a paginated list of the user's organization memberships

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get_organization_memberships(user_id="usr_1234567890", limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user whose organization memberships we want to retrieve	usr_1234567890
limit	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with offset.	20
offset	Optional[int]	➖	Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.	10
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.OrganizationMemberships

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403	application/json
models.SDKError	4XX, 5XX	*/*

get_organization_invitations

Retrieve a paginated list of the user's organization invitations

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get_organization_invitations(user_id="<id>", limit=20, offset=10, status=clerk_backend_api.UsersGetOrganizationInvitationsQueryParamStatus.PENDING)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user whose organization invitations we want to retrieve
limit	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with offset.	20
offset	Optional[int]	➖	Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.	10
status	Optional[models.UsersGetOrganizationInvitationsQueryParamStatus]	➖	Filter organization invitations based on their status
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.OrganizationInvitationsWithPublicOrganizationData

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 403, 404	application/json
models.SDKError	4XX, 5XX	*/*

remove_password

Removes the password credential from the given user. This is a privileged operation and does not require the user's current password. Password removal is allowed even when the user has no other sign-in method configured.

If the user does not have a password, the user is returned unchanged and no password-deletion or user-update event is emitted. By default, existing sessions remain active. Set sign_out_of_other_sessions to true to revoke sessions active when the request is processed.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.remove_password(user_id="<id>", sign_out_of_other_sessions=False)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose password to remove
sign_out_of_other_sessions	Optional[bool]	➖	Set to true to revoke all of the user's active sessions after removing the password.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

verify_password

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.verify_password(user_id="user_123", password="securepassword123")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user for whom to verify the password	user_123
password	str	✔️	The user password to verify	securepassword123
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.VerifyPasswordResponseBody

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

verify_totp

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.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.verify_totp(user_id="usr_1a2b3c", code="123456")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user for whom to verify the TOTP	usr_1a2b3c
code	str	✔️	The TOTP or backup code to verify	123456
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.VerifyTOTPResponseBody

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

disable_mfa

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.disable_mfa(user_id="user_123456")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
user_id	str	✔️	The ID of the user whose MFA methods are to be disabled	user_123456
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DisableMFAResponseBody

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

delete_backup_codes

Disable all of a user's backup codes.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete_backup_codes(user_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose backup codes are to be deleted.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeleteBackupCodeResponseBody

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

delete_passkey

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete_passkey(user_id="<id>", passkey_identification_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user that owns the passkey identity
passkey_identification_id	str	✔️	The ID of the passkey identity to be deleted
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeletedObject

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403, 404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

list_trusted_devices

Returns the active trusted devices enrolled by the user.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.list_trusted_devices(user_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose trusted devices are returned
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.TrustedDeviceList

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403, 404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

revoke_trusted_device

Revokes an active trusted device enrolled by the user.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.revoke_trusted_device(user_id="<id>", trusted_device_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user that owns the trusted device
trusted_device_id	str	✔️	The ID of the trusted device to revoke
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.TrustedDevice

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403, 404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

delete_web3_wallet

Delete the web3 wallet identification for a given user.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete_web3_wallet(user_id="<id>", web3_wallet_identification_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user that owns the web3 wallet
web3_wallet_identification_id	str	✔️	The ID of the web3 wallet identity to be deleted
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeletedObject

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 403, 404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

delete_totp

Deletes all of the user's TOTPs.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete_totp(user_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user whose TOTPs are to be deleted
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeleteTOTPResponseBody

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

delete_external_account

Delete an external account by ID.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.delete_external_account(user_id="<id>", external_account_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user's external account
external_account_id	str	✔️	The ID of the external account to delete
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeletedObject

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 403, 404	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*

set_password_compromised

Sets the given user's password as compromised. The user will be prompted to reset their password on their next sign-in.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.set_password_compromised(user_id="<id>", revoke_all_sessions=False)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user to set the password as compromised
revoke_all_sessions	OptionalNullable[bool]	➖	N/A
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	*/*

unset_password_compromised

Sets the given user's password as no longer compromised. The user will no longer be prompted to reset their password on their next sign-in.

If the user is in reserved-email password quarantine, the quarantine is preserved and the returned user will still have requires_password_reset set to true. Reserved-email password quarantine can only be cleared by completing a password reset or changing/removing the password.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.unset_password_compromised(user_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
user_id	str	✔️	The ID of the user to unset the compromised status for
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.User

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	*/*

get_instance_organization_memberships

Retrieves all organization user memberships for the given instance.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.users.get_instance_organization_memberships(order_by="<value>", limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
order_by	Optional[str]	➖	Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.
limit	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with offset.	20
offset	Optional[int]	➖	Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.	10
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.OrganizationMemberships

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 422	application/json
models.ClerkErrors	500	application/json
models.SDKError	4XX, 5XX	*/*