Users

(users)

Overview

The user object represents a user that has successfully signed up to your application. https://clerk.com/docs/reference/clerkjs/user

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
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
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
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
delete_web3_wallet - Delete a user web3 wallet
create_totp - Create a TOTP for a user
delete_totp - Delete all the user's TOTPs
delete_external_account - Delete External Account

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(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", last_active_at_since=1700690400000, limit=20, offset=10, order_by="-created_at")

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`email_address`	List[str]	➖	Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.	[ "test@example.com" ]
`phone_number`	List[str]	➖	Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.	[ "+12345678901" ]
`external_id`	List[str]	➖	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.	[ "external-id-123" ]
`username`	List[str]	➖	Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.	[ "user123" ]
`web3_wallet`	List[str]	➖	Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored.	[ "0x123456789abcdef0x123456789abcdef" ]
`user_id`	List[str]	➖	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.	[ "user-id-123" ]
`organization_id`	List[str]	➖	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.	[ "org-id-123" ]
`query`	Optional[str]	➖	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.	John
`last_active_at_since`	Optional[int]	➖	Returns users that had session activity since the given date, with day precision. Providing a value with higher precision than day will result in an error. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day.	1700690400000
`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
`order_by`	Optional[str]	➖	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.
`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.

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.

Example Usage

from clerk_backend_api import Clerk

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

    res = clerk.users.create(request={
        "external_id": "ext-id-001",
        "first_name": "John",
        "last_name": "Doe",
        "email_address": [
            "john.doe@example.com",
        ],
        "phone_number": [
            "+12345678901",
        ],
        "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": "argon2i",
        "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,
        "create_organization_enabled": True,
        "create_organizations_limit": 134365,
        "created_at": "2023-03-15T07:15:20.902Z",
    })

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`request`	models.CreateUserRequestBody	✔️	The request object to use for the request.
`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, 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(email_address=[
        "user@example.com",
    ], phone_number=[
        "+1234567890",
    ], external_id=[
        "external-id-123",
    ], username=[
        "username123",
    ], web3_wallet=[
        "0x123456789abcdef",
    ], user_id=[
        "user-id-123",
    ], query="John Doe")

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`email_address`	List[str]	➖	Counts users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.	[ "user@example.com" ]
`phone_number`	List[str]	➖	Counts users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.	[ "+1234567890" ]
`external_id`	List[str]	➖	Counts users with the specified external ids. Accepts up to 100 external ids. Any external ids not found are ignored.	[ "external-id-123" ]
`username`	List[str]	➖	Counts users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored.	[ "username123" ]
`web3_wallet`	List[str]	➖	Counts users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored.	[ "0x123456789abcdef" ]
`user_id`	List[str]	➖	Counts users with the user ids specified. Accepts up to 100 user ids. Any user ids not found are ignored.	[ "user-id-123" ]
`query`	Optional[str]	➖	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.	John Doe
`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")

    assert res is not None

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

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", 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="argon2i", skip_password_checks=False, sign_out_of_other_sessions=True, totp_secret="ABCD1234EFGH5678", backup_codes=[
        "123456",
        "654321",
    ], public_metadata={
        "theme": "dark",
    }, private_metadata={
        "vip": True,
    }, unsafe_metadata={
        "age": 30,
    }, delete_self_enabled=True, create_organization_enabled=False, legal_accepted_at="<value>", skip_legal_checks=False, create_organizations_limit=597129, created_at="2021-04-05T14:30:00.000Z")

    assert res is not None

    # 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
`primary_email_address_id`	Optional[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`	Optional[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`	Optional[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`	Optional[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 can not 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`, `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`	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`	Optional[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. Please note that currently the supported options are: * Period: 30 seconds * Code length: 6 digits * Algorithm: SHA1	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. 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	{ "theme": "dark" }
`private_metadata`	Dict[str, Any]	➖	Metadata saved on the user, that is only visible to your Backend API	{ "vip": true }
`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.	{ "age": 30 }
`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 timestamps 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.
`create_organizations_limit`	OptionalNullable[int]	➖	The maximum number of organizations the user can create. 0 means unlimited.
`created_at`	Optional[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`).	2021-04-05T14:30:00.000Z
`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	/

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

    assert res is not None

    # 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")

    assert res is not None

    # 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")

    assert res is not None

    # 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	/

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

    assert res is not None

    # 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")

    assert res is not None

    # 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"),
        "content_type": "<value>",
    })

    assert res is not None

    # 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")

    assert res is not None

    # 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>",
        "key1": "<value>",
    }, private_metadata={
        "key": "<value>",
        "key1": "<value>",
    }, unsafe_metadata={
        "key": "<value>",
        "key1": "<value>",
    })

    assert res is not None

    # 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	/

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

    assert res is not None

    # 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
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

List[models.ResponseBody]

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 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)

    assert res is not None

    # 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)

    assert res is not None

    # 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	/

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

    assert res is not None

    # 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")

    assert res is not None

    # 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")

    assert res is not None

    # 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, 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>")

    assert res is not None

    # 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, 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>")

    assert res is not None

    # 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, 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>")

    assert res is not None

    # 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, 500	application/json
models.SDKError	4XX, 5XX	/

create_totp

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

Example Usage

from clerk_backend_api import Clerk

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

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

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`user_id`	str	✔️	The ID of the user for whom the TOTP is being created.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Totp

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	403, 404, 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>")

    assert res is not None

    # 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, 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>")

    assert res is not None

    # 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, 500	application/json
models.SDKError	4XX, 5XX	/

Files

README.md

Latest commit

History

README.md

File metadata and controls

Users

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

count

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

ban

Example Usage

Parameters

Response

Errors

unban

Example Usage

Parameters

Response

Errors

lock

Example Usage

Parameters

Response

Errors

unlock

Example Usage

Parameters

Response

Errors

set_profile_image

Example Usage

Parameters

Response

Errors

delete_profile_image

Example Usage

Parameters

Response

Errors

update_metadata

Example Usage

Parameters

Response

Errors

get_o_auth_access_token

Example Usage

Parameters

Response

Errors

get_organization_memberships