Organizationmemberships 5 endpoints

GET /organizations/{organization_id}/memberships

Retrieves all user memberships for the given organization

operationId: OrganizationMemberships_getAllMembers

Parameters

Name In Required Type Description
organization_id path required string

The organization ID.
limit query optional number

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

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 query optional string

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

Responses

200

A list of organization memberships
401

Authentication invalid
422

Invalid request parameters
GET /organizations/{organization_id}/memberships
POST /organizations/{organization_id}/memberships

Adds a user as a member to the given organization.
Only users in the same instance as the organization can be added as members.

operationId: OrganizationMemberships_addUserToOrganization

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization where the new membership will be created

Request Body

required
application/json
schema OrganizationMembershipsAddUserToOrganizationRequest
Property Type Required
role string required
user_id string required

Responses

200

Success
400

Request was not successful
403

Authorization invalid
404

Resource not found
422

Invalid request parameters
POST /organizations/{organization_id}/memberships
DELETE /organizations/{organization_id}/memberships/{user_id}

Removes the given membership from the organization

operationId: OrganizationMemberships_removeUserFromOrganization

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization the membership belongs to
user_id path required string

The ID of the user that this membership belongs to

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
DELETE /organizations/{organization_id}/memberships/{user_id}
PATCH /organizations/{organization_id}/memberships/{user_id}

Updates the properties of an existing organization membership

operationId: OrganizationMemberships_updateMembershipProperties

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization the membership belongs to
user_id path required string

The ID of the user that this membership belongs to

Request Body

required
application/json
schema OrganizationMembershipsUpdateMembershipPropertiesRequest
Property Type Required
role string required

Responses

200

Success
400

Request was not successful
404

Resource not found
422

Invalid request parameters
PATCH /organizations/{organization_id}/memberships/{user_id}
PATCH /organizations/{organization_id}/memberships/{user_id}/metadata

Update an organization membership’s metadata attributes by merging existing values with the provided parameters.
Metadata values will be updated via a deep merge. 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.

operationId: OrganizationMemberships_updateMembershipMetadata

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization the membership belongs to
user_id path required string

The ID of the user that this membership belongs to

Request Body

required
application/json
schema OrganizationMembershipsUpdateMembershipMetadataRequest
Property Type Required
public_metadata object optional
private_metadata object optional

Responses

200

Success
400

Request was not successful
404

Resource not found
422

Invalid request parameters
PATCH /organizations/{organization_id}/memberships/{user_id}/metadata

Organizations 8 endpoints

GET /organizations

This request returns the list of organizations for an instance.
Results can be paginated using the optional limit and offset query parameters.
The organizations are ordered by descending creation date.
Most recent organizations will be returned first.

operationId: Organizations_listSortedByCreationDate

Parameters

Name In Required Type Description
limit query optional number

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

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

Flag to denote whether the member counts of each organization should be included in the response or not.
query query optional string

Returns organizations with ID, name, or slug that match the given query.
Uses exact match for organization ID and partial match for name and slug.
order_by query optional string

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

Responses

200

A list of organizations
400

Request was not successful
403

Authorization invalid
422

Invalid request parameters
GET /organizations
POST /organizations

Creates a new organization with the given name for an instance.
In order to successfully create an organization you need to provide the ID of the User who will become the organization administrator.
You can specify an optional slug for the new organization.
If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash “-“.
Organization slugs must be unique for the instance.
You can provide additional metadata for the organization and set any custom attribute you want.
Organizations support private and public metadata.
Private metadata can only be accessed from the Backend API.
Public metadata can be accessed from the Backend API, and are read-only from the Frontend API.

operationId: Organizations_createNewOrganization

Request Body

application/json
schema OrganizationsCreateNewOrganizationRequest
Property Type Required
name string required
slug string optional
created_by string required
public_metadata object optional
private_metadata object optional
max_allowed_memberships integer optional

Responses

200

An organization
400

Request was not successful
403

Authorization invalid
422

Invalid request parameters
POST /organizations
DELETE /organizations/{organization_id}

Deletes the given organization.
Please note that deleting an organization will also delete all memberships and invitations.
This is not reversible.

operationId: Organizations_deleteOrganization

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization to delete

Responses

200

Deleted Object
404

Resource not found
DELETE /organizations/{organization_id}
GET /organizations/{organization_id}

Fetches the organization whose ID or slug matches the provided id_or_slug URL query parameter.

operationId: Organizations_getByIdOrSlug

Parameters

Name In Required Type Description
organization_id path required string

The ID or slug of the organization

Responses

200

An organization
403

Authorization invalid
404

Resource not found
GET /organizations/{organization_id}
PATCH /organizations/{organization_id}

Updates an existing organization

operationId: Organizations_updateOrganization

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization to update

Request Body

required
application/json
schema OrganizationsUpdateOrganizationRequest
Property Type Required
name string optional
slug string optional
public_metadata object optional
private_metadata object optional
admin_delete_enabled boolean optional
max_allowed_memberships integer optional

Responses

200

An organization
402

Resource not found
404

Resource not found
422

Invalid request parameters
PATCH /organizations/{organization_id}
DELETE /organizations/{organization_id}/logo

Delete the organization’s logo.

operationId: Organizations_removeLogo

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization for which the logo will be deleted.

Responses

200

An organization
404

Resource not found
DELETE /organizations/{organization_id}/logo
PUT /organizations/{organization_id}/logo

Set or replace an organization’s logo, by uploading an image file.
This endpoint uses the multipart/form-data request content type and accepts a file of image type.
The file size cannot exceed 10MB.
Only the following file content types are supported: image/jpeg, image/png, image/gif, image/webp, image/x-icon, image/vnd.microsoft.icon.

operationId: Organizations_updateOrganizationLogo

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization for which to upload a logo

Request Body

multipart/form-data
schema OrganizationsUpdateOrganizationLogoRequest
Property Type Required
file string required
uploader_user_id string required

Responses

200

An organization with a logo URL.
400

Request was not successful
403

Authorization invalid
404

Resource not found
413

Request was not successful
PUT /organizations/{organization_id}/logo
PATCH /organizations/{organization_id}/metadata

Update organization metadata attributes by merging existing values with the provided parameters.
Metadata values will be updated via a deep merge.
Deep meaning that any nested JSON objects will be merged as well.
You can remove metadata keys at any level by setting their value to null.

operationId: Organizations_mergeOrganizationMetadata

Parameters

Name In Required Type Description
organization_id path required string

The ID of the organization for which metadata will be merged or updated

Request Body

required
application/json
schema OrganizationsMergeOrganizationMetadataRequest
Property Type Required
public_metadata object optional
private_metadata object optional

Responses

200

An organization
400

Request was not successful
401

Authentication invalid
404

Resource not found
422

Invalid request parameters
PATCH /organizations/{organization_id}/metadata

Phonenumbers 4 endpoints

POST /phone_numbers

Create a new phone number

operationId: PhoneNumbers_createNewPhoneNumber

Request Body

application/json
schema PhoneNumbersCreateNewPhoneNumberRequest
Property Type Required
primary boolean optional
user_id string optional
verified boolean optional
phone_number string optional
reserved_for_second_factor boolean optional

Responses

200

Success
400

Request was not successful
401

Authentication invalid
403

Authorization invalid
404

Resource not found
422

Invalid request parameters
POST /phone_numbers
DELETE /phone_numbers/{phone_number_id}

Delete the phone number with the given ID

operationId: PhoneNumbers_deletePhoneNumberById

Parameters

Name In Required Type Description
phone_number_id path required string

The ID of the phone number to delete

Responses

200

Deleted Object
400

Request was not successful
401

Authentication invalid
403

Authorization invalid
404

Resource not found
DELETE /phone_numbers/{phone_number_id}
GET /phone_numbers/{phone_number_id}

Returns the details of a phone number

operationId: PhoneNumbers_getDetails

Parameters

Name In Required Type Description
phone_number_id path required string

The ID of the phone number to retrieve

Responses

200

Success
400

Request was not successful
401

Authentication invalid
403

Authorization invalid
404

Resource not found
GET /phone_numbers/{phone_number_id}
PATCH /phone_numbers/{phone_number_id}

Updates a phone number

operationId: PhoneNumbers_updateDetails

Parameters

Name In Required Type Description
phone_number_id path required string

The ID of the phone number to update

Request Body

application/json
schema PhoneNumbersUpdateDetailsRequest
Property Type Required
primary boolean optional
verified boolean optional
reserved_for_second_factor boolean optional

Responses

200

Success
400

Request was not successful
401

Authentication invalid
403

Authorization invalid
404

Resource not found
PATCH /phone_numbers/{phone_number_id}

Proxychecks 1 endpoints

POST /proxy_checks

This endpoint can be used to validate that a proxy-enabled domain is operational.
It tries to verify that the proxy URL provided in the parameters maps to a functional proxy that can reach the Clerk Frontend API.

You can use this endpoint before you set a proxy URL for a domain. This way you can ensure that switching to proxy-based
configuration will not lead to downtime for your instance.

The proxy_url parameter allows for testing proxy configurations for domains that don’t have a proxy URL yet, or operate on
a different proxy URL than the one provided. It can also be used to re-validate a domain that is already configured to work with a proxy.

operationId: ProxyChecks_verifyProxyConfiguration

Request Body

application/json
schema ProxyChecksVerifyProxyConfigurationRequest
Property Type Required
domain_id string optional
proxy_url string optional

Responses

200

Health check information about a domain’s proxy configuration validation attempt.
400

Request was not successful
422

Invalid request parameters
POST /proxy_checks

Redirecturls 4 endpoints

GET /redirect_urls

Lists all whitelisted redirect_urls for the instance

operationId: RedirectUrLs_listAll

Responses

200

List of Redirect URLs
GET /redirect_urls
POST /redirect_urls

Create a redirect URL

operationId: RedirectUrLs_createNewUrl

Request Body

application/json
schema RedirectUrLsCreateNewUrlRequest
Property Type Required
url string optional

Responses

200

Success
400

Request was not successful
422

Invalid request parameters
POST /redirect_urls
DELETE /redirect_urls/{id}

Remove the selected redirect URL from the whitelist of the instance

operationId: RedirectUrLs_removeById

Parameters

Name In Required Type Description
id path required string

The ID of the redirect URL

Responses

200

Deleted Object
404

Resource not found
DELETE /redirect_urls/{id}
GET /redirect_urls/{id}

Retrieve the details of the redirect URL with the given ID

operationId: RedirectUrLs_getById

Parameters

Name In Required Type Description
id path required string

The ID of the redirect URL

Responses

200

Success
404

Resource not found
GET /redirect_urls/{id}

Samlconnections 5 endpoints

GET /saml_connections

Returns the list of SAML Connections for an instance.
Results can be paginated using the optional limit and offset query parameters.
The SAML Connections are ordered by descending creation date and the most recent will be returned first.

operationId: SamlConnectionsBeta_getList

Parameters

Name In Required Type Description
limit query optional number

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

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 SAML Connections
402

Payment required
403

Authorization invalid
422

Invalid request parameters
GET /saml_connections
POST /saml_connections

Create a new SAML Connection.

operationId: SamlConnectionsBeta_createNewConnection

Request Body

application/json
schema SamlConnectionsBetaCreateNewConnectionRequest
Property Type Required
name string required
domain string required
provider string required
idp_sso_url string optional
idp_metadata string optional
idp_entity_id string optional
idp_certificate string optional
idp_metadata_url string optional
attribute_mapping object optional
└ user_id string optional
└ last_name string optional
└ first_name string optional
└ email_address string optional

Responses

200

A SAML Connection
402

Payment required
403

Authorization invalid
422

Invalid request parameters
POST /saml_connections
DELETE /saml_connections/{saml_connection_id}

Deletes the SAML Connection whose ID matches the provided id in the path.

operationId: SamlConnectionsBeta_deleteConnectionById

Parameters

Name In Required Type Description
saml_connection_id path required string

The ID of the SAML Connection to delete

Responses

200

Deleted Object
402

Payment required
403

Authorization invalid
404

Resource not found
DELETE /saml_connections/{saml_connection_id}
GET /saml_connections/{saml_connection_id}

Fetches the SAML Connection whose ID matches the provided saml_connection_id in the path.

operationId: SamlConnectionsBeta_getById

Parameters

Name In Required Type Description
saml_connection_id path required string

The ID of the SAML Connection

Responses

200

A SAML Connection
402

Payment required
403

Authorization invalid
404

Resource not found
GET /saml_connections/{saml_connection_id}
PATCH /saml_connections/{saml_connection_id}

Updates the SAML Connection whose ID matches the provided id in the path.

operationId: SamlConnectionsBeta_updateConnectionById

Parameters

Name In Required Type Description
saml_connection_id path required string

The ID of the SAML Connection to update

Request Body

required
application/json
schema SamlConnectionsBetaUpdateConnectionByIdRequest
Property Type Required
name string optional
active boolean optional
domain string optional
idp_sso_url string optional
idp_metadata string optional
idp_entity_id string optional
idp_certificate string optional
allow_subdomains boolean optional
idp_metadata_url string optional
attribute_mapping object optional
└ user_id string optional
└ last_name string optional
└ first_name string optional
└ email_address string optional
allow_idp_initiated boolean optional
sync_user_attributes boolean optional

Responses

200

A SAML Connection
402

Payment required
403

Authorization invalid
404

Resource not found
422

Invalid request parameters
PATCH /saml_connections/{saml_connection_id}

Sessions 4 endpoints

GET /sessions

Returns a list of all sessions.
The sessions are returned sorted by creation date, with the newest sessions appearing first.
Deprecation Notice (2024-01-01): All parameters were initially considered optional, however
moving forward at least one of client_id or user_id parameters should be provided.

operationId: Sessions_listSortedByCreationDate

Parameters

Name In Required Type Description
client_id query optional string

List sessions for the given client
user_id query optional string

List sessions for the given user
status query optional string

Filter sessions by the provided status
limit query optional number

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

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

Success
400

Request was not successful
401

Authentication invalid
422

Invalid request parameters
GET /sessions
GET /sessions/{session_id}

Retrieve the details of a session

operationId: Sessions_getDetails

Parameters

Name In Required Type Description
session_id path required string

The ID of the session

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
GET /sessions/{session_id}
POST /sessions/{session_id}/revoke

Sets the status of a session as “revoked”, which is an unauthenticated state.
In multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again.

operationId: Sessions_revokeSession

Parameters

Name In Required Type Description
session_id path required string

The ID of the session

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
POST /sessions/{session_id}/revoke
POST /sessions/{session_id}/tokens/{template_name}

Creates a JSON Web Token(JWT) based on a session and a JWT Template name defined for your instance

operationId: Sessions_createSessionTokenFromTemplate

Parameters

Name In Required Type Description
session_id path required string

The ID of the session
template_name path required string

The name of the JWT Template defined in your instance (e.g. custom_hasura).

Responses

200

OK
401

Authentication invalid
404

Resource not found
POST /sessions/{session_id}/tokens/{template_name}

Signintokens 2 endpoints

POST /sign_in_tokens

Creates a new sign-in token and associates it with the given user.
By default, sign-in tokens expire in 30 days.
You can optionally supply a different duration in seconds using the expires_in_seconds property.

operationId: SigninTokens_createToken

Request Body

application/json
schema SigninTokensCreateTokenRequest
Property Type Required
user_id string optional
expires_in_seconds integer optional

Responses

200

Success
404

Resource not found
422

Invalid request parameters
POST /sign_in_tokens
POST /sign_in_tokens/{sign_in_token_id}/revoke

Revokes a pending sign-in token

operationId: SigninTokens_revokeToken

Parameters

Name In Required Type Description
sign_in_token_id path required string

The ID of the sign-in token to be revoked

Responses

200

Success
400

Request was not successful
404

Resource not found
POST /sign_in_tokens/{sign_in_token_id}/revoke

Signups 1 endpoints

PATCH /sign_ups/{id}

Update the sign-up with the given ID

operationId: Signups_updateSignUpById

Parameters

Name In Required Type Description
id path required string

The ID of the sign-up to update

Request Body

application/json
schema SignupsUpdateSignUpByIdRequest
Property Type Required
external_id string optional
custom_action boolean optional

Responses

200

Success
403

Authorization invalid
PATCH /sign_ups/{id}

Users 16 endpoints

GET /users

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

operationId: Users_listSortedByCreationDate

Parameters

Name In Required Type Description
email_address query optional array

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

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

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 query optional array

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

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 query optional array

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 query optional array

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 query optional string

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

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.
limit query optional number

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

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 query optional string

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
POST /users

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.

operationId: Users_createNewUser

Request Body

required
application/json
schema UsersCreateNewUserRequest
Property Type Required
password string optional
username string optional
last_name string optional
created_at string optional
first_name string optional
external_id string optional
totp_secret string optional
web3_wallet array optional
backup_codes array optional
phone_number array optional
email_address array optional
password_digest string optional
password_hasher string optional
public_metadata object optional
unsafe_metadata object optional
private_metadata object optional
skip_password_checks boolean optional
skip_password_requirement boolean optional

Responses

200

Success
400

Request was not successful
401

Authentication invalid
403

Authentication invalid
422

Invalid request parameters
POST /users
GET /users/count

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

operationId: Users_getTotalCount

Parameters

Name In Required Type Description
email_address query optional array

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

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

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

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

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 query optional array

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

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

Responses

200

Success
422

Invalid request parameters
GET /users/count
DELETE /users/{user_id}

Delete the specified user

operationId: Users_deleteUserById

Parameters

Name In Required Type Description
user_id path 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}
GET /users/{user_id}

Retrieve the details of a user

operationId: Users_getUserDetails

Parameters

Name In Required Type Description
user_id path 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}
PATCH /users/{user_id}

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.

operationId: Users_updateUserAttributes

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to update

Request Body

required
application/json
schema UsersUpdateUserAttributesRequest
Property Type Required
password string optional
username string optional
last_name string optional
created_at string optional
first_name string optional
external_id string optional
totp_secret string optional
backup_codes array optional
password_digest string optional
password_hasher string optional
public_metadata object optional
unsafe_metadata object optional
private_metadata object optional
profile_image_id string optional
delete_self_enabled boolean optional
skip_password_checks boolean optional
primary_web3_wallet_id string optional
primary_phone_number_id string optional
primary_email_address_id string optional
sign_out_of_other_sessions boolean optional
…2 more object optional

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
422

Invalid request parameters
PATCH /users/{user_id}
POST /users/{user_id}/ban

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

operationId: Users_markBanned

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to ban

Responses

200

Success
402

Payment required
POST /users/{user_id}/ban
POST /users/{user_id}/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.

operationId: Users_lockUser

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to lock

Responses

200

Success
403

Authorization invalid
POST /users/{user_id}/lock
PATCH /users/{user_id}/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.

operationId: Users_mergeUserMetadataAttributes

Parameters

Name In Required Type Description
user_id path required string

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

Request Body

application/json
schema UsersMergeUserMetadataAttributesRequest
Property Type Required
public_metadata object optional
unsafe_metadata object optional
private_metadata object optional

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
422

Invalid request parameters
PATCH /users/{user_id}/metadata
DELETE /users/{user_id}/mfa

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

operationId: Users_disableMfa

Parameters

Name In Required Type Description
user_id path 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
GET /users/{user_id}/oauth_access_tokens/{provider}

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.

operationId: Users_getOAuthAccessToken

Parameters

Name In Required Type Description
user_id path required string

The ID of the user for which to retrieve the OAuth access token
provider path required string

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

Responses

200

The OAuth access token of the user, if any.
422

Invalid request parameters
GET /users/{user_id}/oauth_access_tokens/{provider}
GET /users/{user_id}/organization_memberships

Retrieve a paginated list of the user’s organization memberships

operationId: Users_getOrganizationMemberships

Parameters

Name In Required Type Description
user_id path required string

The ID of the user whose organization memberships we want to retrieve
limit query optional number

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

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
DELETE /users/{user_id}/profile_image

Delete a user’s profile image

operationId: Users_deleteProfileImage

Parameters

Name In Required Type Description
user_id path 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
POST /users/{user_id}/profile_image

Update a user’s profile image

operationId: Users_setProfileImage

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to update the profile image for

Request Body

required
multipart/form-data
schema UsersSetProfileImageRequest
Property Type Required
file string optional

Responses

200

Success
400

Request was not successful
401

Request was not successful
404

Request was not successful
POST /users/{user_id}/profile_image
POST /users/{user_id}/unban

Removes the ban mark from the given user.

operationId: Users_removeBanFromUser

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to unban

Responses

200

Success
402

Payment required
POST /users/{user_id}/unban
POST /users/{user_id}/unlock

Removes the lock from the given user.

operationId: Users_removeLock

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to unlock

Responses

200

Success
403

Authorization invalid
POST /users/{user_id}/unlock
Load more endpoints