Clerk · Capability
Clerk Backend Api — Users
Clerk Users capability. 31 operations. Lead operation: List All Users.
Capability Spec
naftiko: 1.0.0-alpha2
info:
label: Clerk Backend Api — Users
description: 'Clerk Users capability. 31 operations. Lead operation: List All Users.'
tags:
- Clerk
- Users
created: '2026-05-22'
modified: '2026-05-22'
binds:
- namespace: env
keys:
CLERK_SECRET_KEY: CLERK_SECRET_KEY
capability:
consumes:
- type: http
namespace: clerk-backend-api-users
baseUri: https://api.clerk.com/v1
description: Clerk clerk-backend-api Users business capability.
resources:
- name: users
path: /users
operations:
- name: GetUserList
method: GET
description: List All Users
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: email_address
in: query
type: array
description: 'Returns users with the specified email addresses.
Accepts up to 100 email addresses.
Any email addresses not found are ignored.'
required: false
- name: phone_number
in: query
type: array
description: 'Returns users with the specified phone numbers.
Accepts up to 100 phone numbers.
Any phone numbers not found are ignored.'
required: false
- name: external_id
in: query
type: array
description: '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'
required: false
- name: username
in: query
type: array
description: 'Returns users with the specified usernames.
Accepts up to 100 usernames.
Any usernames not found are ignored.'
required: false
- name: web3_wallet
in: query
type: array
description: 'Returns users with the specified web3 wallet addresses.
Accepts up to 100 web3 wallet addresses.
Any web3 wallet addresses not found are ignored.'
required: false
- name: user_id
in: query
type: array
description: '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.'
required: false
- name: organization_id
in: query
type: array
description: '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 include'
required: false
- name: query
in: query
type: string
description: '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 ma'
required: false
- name: email_address_query
in: query
type: string
description: 'Returns users with emails that match the given query, via case-insensitive partial match.
For example, `email_address_query=ello` will match a user with the email `[email protected]`.'
required: false
- name: phone_number_query
in: query
type: string
description: 'Returns users with phone numbers that match the given query, via case-insensitive partial match.
For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`.'
required: false
- name: username_query
in: query
type: string
description: 'Returns users with usernames that match the given query, via case-insensitive partial match.
For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`.'
required: false
- name: name_query
in: query
type: string
description: Returns users with names that match the given query, via case-insensitive partial match.
required: false
- name: banned
in: query
type: boolean
description: Returns users which are either banned (`banned=true`) or not banned (`banned=false`).
required: false
- name: last_active_at_before
in: query
type: integer
description: 'Returns users whose last session activity was before the given date (with millisecond precision).
Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.'
required: false
- name: last_active_at_after
in: query
type: integer
description: 'Returns users whose last session activity was after the given date (with millisecond precision).
Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.'
required: false
- name: last_active_at_since
in: query
type: integer
description: 'Returns users that had session activity since the given date.
Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day.
Deprecated in favor of `last'
required: false
- name: created_at_before
in: query
type: integer
description: 'Returns users who have been created before the given date (with millisecond precision).
Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.'
required: false
- name: created_at_after
in: query
type: integer
description: 'Returns users who have been created after the given date (with millisecond precision).
Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.'
required: false
- name: last_sign_in_at_before
in: query
type: integer
description: 'Returns users whose last sign-in was before the given date (with millisecond precision).
Example: use 1700690400000 to retrieve users whose last sign-in was before 2023-11-23.'
required: false
- name: last_sign_in_at_after
in: query
type: integer
description: 'Returns users whose last sign-in was after the given date (with millisecond precision).
Example: use 1700690400000 to retrieve users whose last sign-in was after 2023-11-23.'
required: false
- name: provider
in: query
type: string
description: 'Returns users with external accounts for the specified OAuth provider.
Must be used in combination with the `provider_user_id` parameter.
For example, use `provider=oauth_google&provider_user_id=12345'
required: false
- name: provider_user_id
in: query
type: array
description: 'Returns users with the specified provider user IDs for a specific provider.
Must be used in combination with the `provider` parameter.
For example, use `provider=oauth_google&provider_user_id=12345` t'
required: false
- name: order_by
in: query
type: string
description: '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`,`u'
required: false
- name: CreateUser
method: POST
description: Create a New User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-count
path: /users/count
operations:
- name: GetUsersCount
method: GET
description: Count Users
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: email_address
in: query
type: array
description: 'Counts users with the specified email addresses.
Accepts up to 100 email addresses.
Any email addresses not found are ignored.'
required: false
- name: phone_number
in: query
type: array
description: 'Counts users with the specified phone numbers.
Accepts up to 100 phone numbers.
Any phone numbers not found are ignored.'
required: false
- name: external_id
in: query
type: array
description: 'Counts users with the specified external IDs.
Accepts up to 100 external IDs.
Any external IDs not found are ignored.'
required: false
- name: username
in: query
type: array
description: 'Counts users with the specified usernames.
Accepts up to 100 usernames.
Any usernames not found are ignored.'
required: false
- name: web3_wallet
in: query
type: array
description: 'Counts users with the specified web3 wallet addresses.
Accepts up to 100 web3 wallet addresses.
Any web3 wallet addresses not found are ignored.'
required: false
- name: user_id
in: query
type: array
description: 'Counts users with the user IDs specified.
Accepts up to 100 user IDs.
Any user IDs not found are ignored.'
required: false
- name: organization_id
in: query
type: array
description: '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 include'
required: false
- name: query
in: query
type: string
description: '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 mat'
required: false
- name: email_address_query
in: query
type: string
description: 'Counts users with emails that match the given query, via case-insensitive partial match.
For example, `email_address_query=ello` will match a user with the email `[email protected]`,
and will be inclu'
required: false
- name: phone_number_query
in: query
type: string
description: 'Counts users with phone numbers that match the given query, via case-insensitive partial match.
For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`,
and will b'
required: false
- name: username_query
in: query
type: string
description: 'Counts users with usernames that match the given query, via case-insensitive partial match.
For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`,
and will be inclu'
required: false
- name: name_query
in: query
type: string
description: Returns users with names that match the given query, via case-insensitive partial match.
required: false
- name: banned
in: query
type: boolean
description: Counts users which are either banned (`banned=true`) or not banned (`banned=false`).
required: false
- name: last_active_at_before
in: query
type: integer
description: 'Returns users whose last session activity was before the given date (with millisecond precision).
Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.'
required: false
- name: last_active_at_after
in: query
type: integer
description: 'Returns users whose last session activity was after the given date (with millisecond precision).
Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.'
required: false
- name: last_active_at_since
in: query
type: integer
description: 'Returns users that had session activity since the given date.
Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day.
Deprecated in favor of `last'
required: false
- name: created_at_before
in: query
type: integer
description: 'Returns users who have been created before the given date (with millisecond precision).
Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.'
required: false
- name: created_at_after
in: query
type: integer
description: 'Returns users who have been created after the given date (with millisecond precision).
Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.'
required: false
- name: last_sign_in_at_before
in: query
type: integer
description: 'Counts users whose last sign-in was before the given date (with millisecond precision).
Example: use 1700690400000 to count users whose last sign-in was before 2023-11-23.'
required: false
- name: last_sign_in_at_after
in: query
type: integer
description: 'Counts users whose last sign-in was after the given date (with millisecond precision).
Example: use 1700690400000 to count users whose last sign-in was after 2023-11-23.'
required: false
- name: provider
in: query
type: string
description: 'Counts users with external accounts for the specified OAuth provider.
Must be used in combination with the `provider_user_id` parameter.
For example, use `provider=oauth_google&provider_user_id=12345`'
required: false
- name: provider_user_id
in: query
type: array
description: 'Counts users with the specified provider user IDs for a specific provider.
Must be used in combination with the `provider` parameter.
For example, use `provider=oauth_google&provider_user_id=12345` to'
required: false
- name: users-user-id
path: /users/{user_id}
operations:
- name: GetUser
method: GET
description: Retrieve a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to retrieve
required: true
- name: UpdateUser
method: PATCH
description: Update a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to update
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: DeleteUser
method: DELETE
description: Delete a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to delete
required: true
- name: users-user-id-ban
path: /users/{user_id}/ban
operations:
- name: BanUser
method: POST
description: Ban a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to ban
required: true
- name: users-user-id-unban
path: /users/{user_id}/unban
operations:
- name: UnbanUser
method: POST
description: Unban a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to unban
required: true
- name: users-ban
path: /users/ban
operations:
- name: UsersBan
method: POST
description: Ban Multiple Users
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-unban
path: /users/unban
operations:
- name: UsersUnban
method: POST
description: Unban Multiple Users
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-user-id-lock
path: /users/{user_id}/lock
operations:
- name: LockUser
method: POST
description: Lock a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to lock
required: true
- name: users-user-id-unlock
path: /users/{user_id}/unlock
operations:
- name: UnlockUser
method: POST
description: Unlock a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to unlock
required: true
- name: users-user-id-profile-image
path: /users/{user_id}/profile_image
operations:
- name: SetUserProfileImage
method: POST
description: Set User Profile Image
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to update the profile image for
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: DeleteUserProfileImage
method: DELETE
description: Delete User Profile Image
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to delete the profile image for
required: true
- name: users-user-id-metadata
path: /users/{user_id}/metadata
operations:
- name: UpdateUserMetadata
method: PATCH
description: Merge and Update a User's Metadata
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose metadata will be updated and merged
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-user-id-billing-subscription
path: /users/{user_id}/billing/subscription
operations:
- name: GetUserBillingSubscription
method: GET
description: Retrieve a User's Billing Subscription
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose subscription to retrieve
required: true
- name: users-user-id-billing-credits
path: /users/{user_id}/billing/credits
operations:
- name: GetUserBillingCreditBalance
method: GET
description: Retrieve a User's Credit Balance
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose credit balance to retrieve
required: true
- name: AdjustUserBillingCreditBalance
method: POST
description: Adjust a User's Credit Balance
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose credit balance to adjust
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-user-id-oauth-access-tokens-provider
path: /users/{user_id}/oauth_access_tokens/{provider}
operations:
- name: GetOAuthAccessToken
method: GET
description: Retrieve the OAuth Access Token of a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user for which to retrieve the OAuth access token
required: true
- name: provider
in: path
type: string
description: The ID of the OAuth provider (e.g. `oauth_google`)
required: true
- name: users-user-id-organization-memberships
path: /users/{user_id}/organization_memberships
operations:
- name: UsersGetOrganizationMemberships
method: GET
description: Retrieve All Memberships for a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose organization memberships we want to retrieve
required: true
- name: users-user-id-organization-invitations
path: /users/{user_id}/organization_invitations
operations:
- name: UsersGetOrganizationInvitations
method: GET
description: Retrieve All Invitations for a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose organization invitations we want to retrieve
required: true
- name: status
in: query
type: string
description: Filter organization invitations based on their status
required: false
- name: users-user-id-verify-password
path: /users/{user_id}/verify_password
operations:
- name: VerifyPassword
method: POST
description: Verify the Password of a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user for whom to verify the password
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-user-id-verify-totp
path: /users/{user_id}/verify_totp
operations:
- name: VerifyTOTP
method: POST
description: Verify a TOTP or Backup Code for a User
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user for whom to verify the TOTP
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-user-id-mfa
path: /users/{user_id}/mfa
operations:
- name: DisableMFA
method: DELETE
description: Disable a User's MFA Methods
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose MFA methods are to be disabled
required: true
- name: users-user-id-backup-code
path: /users/{user_id}/backup_code
operations:
- name: DeleteBackupCode
method: DELETE
description: Disable All User's Backup Codes
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose backup codes are to be deleted.
required: true
- name: users-user-id-passkeys-passkey-identification-id
path: /users/{user_id}/passkeys/{passkey_identification_id}
operations:
- name: UserPasskeyDelete
method: DELETE
description: Delete a User Passkey
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user that owns the passkey identity
required: true
- name: passkey_identification_id
in: path
type: string
description: The ID of the passkey identity to be deleted
required: true
- name: users-user-id-web3-wallets-web3-wallet-identification-id
path: /users/{user_id}/web3_wallets/{web3_wallet_identification_id}
operations:
- name: UserWeb3WalletDelete
method: DELETE
description: Delete a User Web3 Wallet
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user that owns the web3 wallet
required: true
- name: web3_wallet_identification_id
in: path
type: string
description: The ID of the web3 wallet identity to be deleted
required: true
- name: users-user-id-totp
path: /users/{user_id}/totp
operations:
- name: DeleteTOTP
method: DELETE
description: Delete All the User's TOTPs
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user whose TOTPs are to be deleted
required: true
- name: users-user-id-external-accounts-external-account-id
path: /users/{user_id}/external_accounts/{external_account_id}
operations:
- name: DeleteExternalAccount
method: DELETE
description: Delete External Account
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user's external account
required: true
- name: external_account_id
in: path
type: string
description: The ID of the external account to delete
required: true
- name: users-user-id-password-set-compromised
path: /users/{user_id}/password/set_compromised
operations:
- name: SetUserPasswordCompromised
method: POST
description: Set a User's Password as Compromised
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to set the password as compromised
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: true
- name: users-user-id-password-unset-compromised
path: /users/{user_id}/password/unset_compromised
operations:
- name: UnsetUserPasswordCompromised
method: POST
description: Unset a User's Password as Compromised
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: user_id
in: path
type: string
description: The ID of the user to unset the compromised status for
required: true