@lap v0.3 # Machine-readable API spec. Each @endpoint block is one API call. @api Clerk Backend API @base https://api.clerk.com/v1 @version 2025-11-10 @auth Bearer bearer @endpoints 206 @hint download_for_search @toc public(1), jwks(1), clients(3), email_addresses(4), phone_numbers(4), sessions(7), templates(6), users(31), invitations(4), organization_invitations(1), allowlist_identifiers(3), blocklist_identifiers(3), beta_features(2), actor_tokens(2), domains(4), instance(9), webhooks(3), jwt_templates(5), machines(9), organizations(26), organization_roles(7), organization_domains(1), proxy_checks(1), redirect_urls(4), sign_in_tokens(2), sign_ups(2), oauth_applications(7), saml_connections(5), enterprise_connections(5), testing_tokens(1), agents(2), organization_memberships(1), waitlist_entries(6), billing(10), organization_permissions(5), role_sets(7), api_keys(8), m2m_tokens(4) @group public @endpoint GET /public/interstitial @desc Returns the markup for the interstitial page @optional {frontendApi: str # Please use `frontend_api` instead, frontend_api: str # The Frontend API key of your instance, publishable_key: str # The publishable key of your instance, proxy_url: str # The proxy URL of your instance, domain: str # The domain of your instance, sign_in_url: str # The sign in URL of your instance, use_domain_for_script: bool # Whether to use the domain for the script URL} @returns(200) The interstitial page markup @errors {400: A required query parameter is missing, 500: An infinite redirect loop was detected} @endgroup @group jwks @endpoint GET /jwks @desc Retrieve the JSON Web Key Set of the instance @returns(200) {keys: [any]} # Get the JSON Web Key Set @endgroup @group clients @endpoint GET /clients @desc List all clients @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 410: The endpoint is considered deprecated and is pending removal., 422: Invalid request parameters} @endpoint POST /clients/verify @desc Verify a client @required {token: str # A JWT that represents the active client.} @returns(200) {object: str, id: str, session_ids: [str], sessions: [map], sign_in_id: str?, sign_up_id: str?, last_active_session_id: str?, last_authentication_strategy: str?, updated_at: int(int64), created_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endpoint GET /clients/{client_id} @desc Get a client @required {client_id: str # Client ID.} @returns(200) {object: str, id: str, session_ids: [str], sessions: [map], sign_in_id: str?, sign_up_id: str?, last_active_session_id: str?, last_authentication_strategy: str?, updated_at: int(int64), created_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endgroup @group email_addresses @endpoint POST /email_addresses @desc Create an email address @required {user_id: str # The ID representing the user, email_address: str # The new email address. Must adhere to the RFC 5322 specification for email address format.} @optional {verified: bool # When created, the email address will be marked as verified., primary: bool # Create this email address as the primary email address for the user. Default: false, unless it is the first email address.} @returns(200) {id: str, object: str, email_address: str, reserved: bool, verification: map?, linked_to: [map], matches_sso_connection: bool, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Conflict, 422: Invalid request parameters} @endpoint GET /email_addresses/{email_address_id} @desc Retrieve an email address @required {email_address_id: str # The ID of the email address to retrieve} @returns(200) {id: str, object: str, email_address: str, reserved: bool, verification: map?, linked_to: [map], matches_sso_connection: bool, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endpoint DELETE /email_addresses/{email_address_id} @desc Delete an email address @required {email_address_id: str # The ID of the email address to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Conflict} @endpoint PATCH /email_addresses/{email_address_id} @desc Update an email address @required {email_address_id: str # The ID of the email address to update} @optional {verified: bool # The email address will be marked as verified., primary: bool # Set this email address as the primary email address for the user.} @returns(200) {id: str, object: str, email_address: str, reserved: bool, verification: map?, linked_to: [map], matches_sso_connection: bool, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Conflict} @endgroup @group phone_numbers @endpoint POST /phone_numbers @desc Create a phone number @required {user_id: str # The ID representing the user, phone_number: str # The new phone number. Must adhere to the E.164 standard for phone number format.} @optional {verified: bool # When created, the phone number will be marked as verified., primary: bool # Create this phone number as the primary phone number for the user. Default: false, unless it is the first phone number., reserved_for_second_factor: bool # Create this phone number as reserved for multi-factor authentication. The phone number must also be verified. If there are no other reserved second factors, the phone number will be set as the default second factor.} @returns(200) {id: str, object: str, phone_number: str, reserved_for_second_factor: bool, default_second_factor: bool, reserved: bool, verification: map?, linked_to: [map], backup_codes: [str]?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /phone_numbers/{phone_number_id} @desc Retrieve a phone number @required {phone_number_id: str # The ID of the phone number to retrieve} @returns(200) {id: str, object: str, phone_number: str, reserved_for_second_factor: bool, default_second_factor: bool, reserved: bool, verification: map?, linked_to: [map], backup_codes: [str]?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endpoint DELETE /phone_numbers/{phone_number_id} @desc Delete a phone number @required {phone_number_id: str # The ID of the phone number to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endpoint PATCH /phone_numbers/{phone_number_id} @desc Update a phone number @required {phone_number_id: str # The ID of the phone number to update} @optional {verified: bool # The phone number will be marked as verified., primary: bool # Set this phone number as the primary phone number for the user., reserved_for_second_factor: bool # Set this phone number as reserved for multi-factor authentication. The phone number must also be verified. If there are no other reserved second factors, the phone number will be set as the default second factor.} @returns(200) {id: str, object: str, phone_number: str, reserved_for_second_factor: bool, default_second_factor: bool, reserved: bool, verification: map?, linked_to: [map], backup_codes: [str]?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endgroup @group sessions @endpoint GET /sessions @desc List all sessions @optional {client_id: str # List sessions for the given client, user_id: str # List sessions for the given user, status: str(abandoned/active/ended/expired/removed/replaced/revoked) # Filter sessions by the provided status, paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters} @endpoint POST /sessions @desc Create a new active session @required {user_id: str # The ID representing the user} @optional {active_organization_id: str # The ID of the organization to set as active for this session} @returns(200) {object: str, id: str, user_id: str, client_id: str, actor: map?, status: str, last_active_organization_id: str?, last_active_at: int, latest_activity: map?{object: str, id: str, device_type: str, is_mobile: bool, browser_name: str, browser_version: str, ip_address: str, city: str, country: str}, expire_at: int(int64), abandon_at: int(int64), updated_at: int(int64), created_at: int(int64), tasks: [map]?} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Request was not successful, 422: Invalid request parameters} @endpoint GET /sessions/{session_id} @desc Retrieve a session @required {session_id: str # The ID of the session} @returns(200) {object: str, id: str, user_id: str, client_id: str, actor: map?, status: str, last_active_organization_id: str?, last_active_at: int, latest_activity: map?{object: str, id: str, device_type: str, is_mobile: bool, browser_name: str, browser_version: str, ip_address: str, city: str, country: str}, expire_at: int(int64), abandon_at: int(int64), updated_at: int(int64), created_at: int(int64), tasks: [map]?} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endpoint POST /sessions/{session_id}/refresh @desc Refresh a session @required {session_id: str # The ID of the session, expired_token: str # The JWT that is sent via the `__session` cookie from your frontend. Note: this JWT must be associated with the supplied session ID., refresh_token: str # The refresh token from the `__refresh` cookie set via FAPI's handshake flow., request_origin: str # The origin of the request.} @optional {request_headers: map # The headers of the request., format: str(token/cookie)=token # The format of the response., request_originating_ip: str # The IP address of the request.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid} @endpoint POST /sessions/{session_id}/revoke @desc Revoke a session @required {session_id: str # The ID of the session} @returns(200) {object: str, id: str, user_id: str, client_id: str, actor: map?, status: str, last_active_organization_id: str?, last_active_at: int, latest_activity: map?{object: str, id: str, device_type: str, is_mobile: bool, browser_name: str, browser_version: str, ip_address: str, city: str, country: str}, expire_at: int(int64), abandon_at: int(int64), updated_at: int(int64), created_at: int(int64), tasks: [map]?} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endpoint POST /sessions/{session_id}/tokens @desc Create a session token @required {session_id: str # The ID of the session} @optional {expires_in_seconds: int # Use this parameter to override the default session token lifetime.} @returns(200) {object: str, jwt: str} # OK @errors {401: Authentication invalid, 404: Resource not found} @endpoint POST /sessions/{session_id}/tokens/{template_name} @desc Create a session token from a JWT template @required {session_id: str # The ID of the session, template_name: str # The name of the JWT template defined in your instance (e.g. `custom_hasura`).} @optional {expires_in_seconds: int # Use this parameter to override the JWT lifetime.} @returns(200) {object: str, jwt: str} # OK @errors {401: Authentication invalid, 404: Resource not found} @endgroup @group templates @endpoint GET /templates/{template_type} @desc List all templates @required {template_type: str(email/sms) # The type of templates to list (email or SMS)} @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters} @endpoint GET /templates/{template_type}/{slug} @desc Retrieve a template @required {template_type: str(email/sms) # The type of templates to retrieve (email or SMS), slug: str # The slug (i.e. machine-friendly name) of the template to retrieve} @returns(200) {id: str, object: str, instance_id: str?, resource_type: str, template_type: str, name: str, slug: str, position: int, can_revert: bool, can_delete: bool, can_edit_body: bool, can_toggle: bool, subject: str?, markup: str, body: str, available_variables: [str], required_variables: [str], from_email_name: str, reply_to_email_name: str, delivered_by_clerk: bool, enabled: bool, flagged_as_suspicious: bool, updated_at: int(int64), created_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endpoint PUT /templates/{template_type}/{slug} @desc Update a template for a given type and slug @required {template_type: str(email/sms) # The type of template to update, slug: str # The slug of the template to update} @optional {name: str # The user-friendly name of the template, subject: str # The email subject. Applicable only to email templates., markup: str # The editor markup used to generate the body of the template, body: str # The template body before variable interpolation, delivered_by_clerk: bool # Whether Clerk should deliver emails or SMS messages based on the current template, from_email_name: str # The local part of the From email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates., reply_to_email_name: str # The local part of the Reply To email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates.} @returns(200) {id: str, object: str, instance_id: str?, resource_type: str, template_type: str, name: str, slug: str, position: int, can_revert: bool, can_delete: bool, can_edit_body: bool, can_toggle: bool, subject: str?, markup: str, body: str, available_variables: [str], required_variables: [str], from_email_name: str, reply_to_email_name: str, delivered_by_clerk: bool, enabled: bool, flagged_as_suspicious: bool, updated_at: int(int64), created_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 402: Payment required, 403: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /templates/{template_type}/{slug}/revert @desc Revert a template @required {template_type: str(email/sms) # The type of template to revert, slug: str # The slug of the template to revert} @returns(200) {id: str, object: str, instance_id: str?, resource_type: str, template_type: str, name: str, slug: str, position: int, can_revert: bool, can_delete: bool, can_edit_body: bool, can_toggle: bool, subject: str?, markup: str, body: str, available_variables: [str], required_variables: [str], from_email_name: str, reply_to_email_name: str, delivered_by_clerk: bool, enabled: bool, flagged_as_suspicious: bool, updated_at: int(int64), created_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 402: Payment required, 404: Resource not found} @endpoint POST /templates/{template_type}/{slug}/preview @desc Preview changes to a template @required {template_type: str # The type of template to preview, slug: str # The slug of the template to preview} @optional {subject: str # The email subject. Applicable only to email templates., body: str # The template body before variable interpolation, from_email_name: str # The local part of the From email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates., reply_to_email_name: str # The local part of the Reply To email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates.} @returns(200) OK @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /templates/{template_type}/{slug}/toggle_delivery @desc Toggle the delivery by Clerk for a template of a given type and slug @required {template_type: str(email/sms) # The type of template to toggle delivery for, slug: str # The slug of the template for which to toggle delivery} @optional {delivered_by_clerk: bool # Whether Clerk should deliver emails or SMS messages based on the current template} @returns(200) {id: str, object: str, instance_id: str?, resource_type: str, template_type: str, name: str, slug: str, position: int, can_revert: bool, can_delete: bool, can_edit_body: bool, can_toggle: bool, subject: str?, markup: str, body: str, available_variables: [str], required_variables: [str], from_email_name: str, reply_to_email_name: str, delivered_by_clerk: bool, enabled: bool, flagged_as_suspicious: bool, updated_at: int(int64), created_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endgroup @group users @endpoint GET /users @desc List all users @optional {email_address: [str] # Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored., phone_number: [str] # Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored., external_id: [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., username: [str] # Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored., web3_wallet: [str] # Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addresses not found are ignored., user_id: [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., organization_id: [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., query: 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., email_address_query: str # Returns users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`., phone_number_query: str # Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`., username_query: str # Returns users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`., name_query: str # Returns users with names that match the given query, via case-insensitive partial match., banned: bool # Returns users which are either banned (`banned=true`) or not banned (`banned=false`)., last_active_at_before: int # 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., last_active_at_after: int # 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., last_active_at_since: int # Returns users that had session activity since the given date. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. Deprecated in favor of `last_active_at_after`., created_at_before: int # 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., created_at_after: int # 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., last_sign_in_at_before: int # 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., last_sign_in_at_after: int # 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., provider: str # 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` to retrieve a user with Google provider user ID 12345., provider_user_id: [str] # 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` to retrieve a user with Google provider user ID 12345. Accepts up to 100 provider user IDs. Any provider user IDs not found are ignored., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., order_by: str=-created_at # Allows to return users in a particular order. At the moment, you can order the returned users by their `created_at`,`updated_at`,`email_address`,`web3wallet`,`first_name`,`last_name`,`phone_number`,`username`,`last_active_at`,`last_sign_in_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, if you pass `order_by=username&order_by=created_at`, we will consider only the first `order_by` parameter, which is `username`. The `created_at` parameter will be ignored in this case.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters} @endpoint POST /users @desc Create a new user @optional {external_id: str # The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance., first_name: str # The first name to assign to the user, last_name: str # The last name to assign to the user, locale: str # The locale to assign to the user (e.g., "en-US", "fr-FR"), email_address: [str] # Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the user's primary email address., phone_number: [str] # Phone numbers to add to the user. Must be unique across your instance. The first phone number will be set as the user's primary phone number., web3_wallet: [str] # Web3 wallets to add to the user. Must be unique across your instance. The first wallet will be set as the user's primary wallet., username: str # The username to give to the user. It must be unique across your instance., password: str # The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords., password_digest: 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., password_hasher: str # The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html), the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`, and `sha512_symfony`, the SHA-512 variant of the [Symfony](https://symfony.com/doc/current/security/passwords.html) legacy hasher. Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information., skip_password_checks: bool # When set to `true` all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password., skip_password_requirement: bool # When set to `true`, `password` is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. Please note that you cannot use this flag if password is the only way for a user to sign into your instance., totp_secret: str # In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Please note that currently the supported options are: * Period: 30 seconds * Code length: 6 digits * Algorithm: SHA1, backup_codes: [str] # If Backup Codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest., public_metadata: map # Metadata saved on the user, that is visible to both your Frontend and Backend APIs, private_metadata: map # Metadata saved on the user, that is only visible to your Backend API, unsafe_metadata: map # Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe., delete_self_enabled: bool # If enabled, user can delete themselves via FAPI., legal_accepted_at: str # A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`)., skip_legal_checks: bool # When set to `true` all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk., skip_user_requirement: bool # When set to `true`, identification types are not enforced. At least one identification type must be enabled and provided on your instance (email, phone, web3 wallet, or username). Users created without required identification types cannot use those authentication strategies It is not recommended to use this flag unless you need to allow Clerk UI components to prompt for required fields while BAPI creates users with minimal data, or for migration a user to Clerk., create_organization_enabled: bool # If enabled, user can create organizations via FAPI., create_organizations_limit: int # The maximum number of organizations the user can create. 0 means unlimited., created_at: 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`)., bypass_client_trust: bool # When set to `true`, the user will bypass client trust checks during sign-in.} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authentication invalid, 422: Invalid request parameters} @endpoint GET /users/count @desc Count users @optional {email_address: [str] # Counts users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored., phone_number: [str] # Counts users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored., external_id: [str] # Counts users with the specified external IDs. Accepts up to 100 external IDs. Any external IDs not found are ignored., username: [str] # Counts users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored., web3_wallet: [str] # Counts users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addresses not found are ignored., user_id: [str] # Counts users with the user IDs specified. Accepts up to 100 user IDs. Any user IDs not found are ignored., organization_id: [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., query: 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., email_address_query: str # Counts users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`, and will be included in the resulting count., phone_number_query: str # Counts users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`, and will be included in the resulting count., username_query: str # Counts users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`, and will be included in the resulting count., name_query: str # Returns users with names that match the given query, via case-insensitive partial match., banned: bool # Counts users which are either banned (`banned=true`) or not banned (`banned=false`)., last_active_at_before: int # 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., last_active_at_after: int # 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., last_active_at_since: int # Returns users that had session activity since the given date. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. Deprecated in favor of `last_active_at_after`., created_at_before: int # 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., created_at_after: int # 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., last_sign_in_at_before: int # 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., last_sign_in_at_after: int # 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., provider: str # 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` to count users with Google provider user ID 12345. Accepts up to 100 providers., provider_user_id: [str] # 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 count users with Google provider user ID 12345. Accepts up to 100 provider user IDs. Any provider user IDs not found are ignored.} @returns(200) {object: str, total_count: int(int64)} # Success @errors {422: Invalid request parameters} @endpoint GET /users/{user_id} @desc Retrieve a user @required {user_id: str # The ID of the user to retrieve} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endpoint PATCH /users/{user_id} @desc Update a user @required {user_id: str # The ID of the user to update} @optional {external_id: str # The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance., first_name: str # The first name to assign to the user, last_name: str # The last name to assign to the user, locale: str # The locale to assign to the user (e.g., "en-US", "fr-FR"), primary_email_address_id: str # The ID of the email address to set as primary. It must be verified, and present on the current user., notify_primary_email_address_changed: bool=false # If set to `true`, the user will be notified that their primary email address has changed. By default, no notification is sent., primary_phone_number_id: str # The ID of the phone number to set as primary. It must be verified, and present on the current user., primary_web3_wallet_id: str # The ID of the web3 wallets to set as primary. It must be verified, and present on the current user., username: str # The username to give to the user. It must be unique across your instance., profile_image_id: str # The ID of the image to set as the user's profile image, password: str # The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords., password_digest: 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., password_hasher: str # The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html), the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`, and `sha512_symfony`, the SHA-512 variant of the [Symfony](https://symfony.com/doc/current/security/passwords.html) legacy hasher. Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information., skip_password_checks: 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`., sign_out_of_other_sessions: 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`., totp_secret: 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, backup_codes: [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., public_metadata: map # Metadata saved on the user, that is visible to both your Frontend and Backend APIs, private_metadata: map # Metadata saved on the user, that is only visible to your Backend API, unsafe_metadata: map # Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe., delete_self_enabled: bool # If true, the user can delete themselves with the Frontend API., create_organization_enabled: bool # If true, the user can create organizations with the Frontend API., legal_accepted_at: str # A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`)., skip_legal_checks: 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: int # The maximum number of organizations the user can create. 0 means unlimited., created_at: 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`)., bypass_client_trust: bool # When set to `true`, the user will bypass client trust checks during sign-in.} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 409: Conflict, 422: Invalid request parameters} @endpoint DELETE /users/{user_id} @desc Delete a user @required {user_id: str # The ID of the user to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endpoint POST /users/{user_id}/ban @desc Ban a user @required {user_id: str # The ID of the user to ban} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {402: Payment required} @endpoint POST /users/{user_id}/unban @desc Unban a user @required {user_id: str # The ID of the user to unban} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {402: Payment required} @endpoint POST /users/ban @desc Ban multiple users @required {user_ids: [str] # Array of user IDs to ban} @returns(200) Success @errors {400: Request was not successful, 402: Payment required} @endpoint POST /users/unban @desc Unban multiple users @required {user_ids: [str] # Array of user IDs to unban} @returns(200) Success @errors {400: Request was not successful, 402: Payment required} @endpoint POST /users/{user_id}/lock @desc Lock a user @required {user_id: str # The ID of the user to lock} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {403: Authorization invalid} @endpoint POST /users/{user_id}/unlock @desc Unlock a user @required {user_id: str # The ID of the user to unlock} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {403: Authorization invalid} @endpoint POST /users/{user_id}/profile_image @desc Set user profile image @required {user_id: str # The ID of the user to update the profile image for} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Request was not successful, 404: Request was not successful} @endpoint DELETE /users/{user_id}/profile_image @desc Delete user profile image @required {user_id: str # The ID of the user to delete the profile image for} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {404: Request was not successful} @endpoint PATCH /users/{user_id}/metadata @desc Merge and update a user's metadata @required {user_id: str # The ID of the user whose metadata will be updated and merged} @optional {public_metadata: map # 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: map # Metadata saved on the user that is only visible to your backend. The new object will be merged with the existing value., unsafe_metadata: map # 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.} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /users/{user_id}/billing/subscription @desc Retrieve a user's billing subscription @required {user_id: str # The ID of the user whose subscription to retrieve} @returns(200) {object: str, id: str, instance_id: str, status: str, payer_id: str, created_at: int(int64), updated_at: int(int64), active_at: int(int64)?, past_due_at: int(int64)?, subscription_items: [map], next_payment: map{date: int(int64), amount: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}}, eligible_for_free_trial: bool} # A commerce subscription. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /users/{user_id}/billing/credits @desc Retrieve a user's credit balance @required {user_id: str # The ID of the user whose credit balance to retrieve} @returns(200) {object: str, balance: any?} # A payer's credit balance. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint POST /users/{user_id}/billing/credits @desc Adjust a user's credit balance @required {user_id: str # The ID of the user whose credit balance to adjust, amount: int(int64) # The credit amount in cents. Must be greater than zero., action: str(increase/decrease) # Whether to increase or decrease the credit balance., idempotency_key: str # A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry.} @optional {currency: str # The currency code (e.g. "USD"). Defaults to USD if not provided., note: str # An optional note to attach to the ledger entry.} @returns(200) {object: str, id: str, payer_id: str, amount: int(int64), currency: str, source_type: str, source_id: str, note: str?, created_at: str(date-time)} # A credit ledger entry. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Request was not successful, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /users/{user_id}/oauth_access_tokens/{provider} @desc Retrieve the OAuth access token of a user @required {user_id: str # The ID of the user for which to retrieve the OAuth access token, provider: str # The ID of the OAuth provider (e.g. `oauth_google`)} @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) Success @errors {400: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /users/{user_id}/organization_memberships @desc Retrieve all memberships for a user @required {user_id: str # The ID of the user whose organization memberships we want to retrieve} @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization memberships @errors {403: Request was not successful} @endpoint GET /users/{user_id}/organization_invitations @desc Retrieve all invitations for a user @required {user_id: str # The ID of the user whose organization invitations we want to retrieve} @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., status: str(pending/accepted/revoked/expired) # Filter organization invitations based on their status} @returns(200) {data: [map], total_count: int(int64)} # A list of organization invitations with public organization data @errors {400: Request was not successful, 403: Request was not successful, 404: Resource not found} @endpoint POST /users/{user_id}/verify_password @desc Verify the password of a user @required {user_id: str # The ID of the user for whom to verify the password, password: str # The user password to verify} @returns(200) {verified: bool} # The provided password was correct. @errors {400: The user does not have a password set., 404: The user does not exist., 422: The provided password was incorrect., 500: Request was not successful} @endpoint POST /users/{user_id}/verify_totp @desc Verify a TOTP or backup code for a user @required {user_id: str # The ID of the user for whom to verify the TOTP, code: str # The TOTP or backup code to verify} @returns(200) {verified: bool, code_type: str} # The provided TOTP or backup code was correct. @errors {400: The user does not have TOTP configured for their account., 404: The user does not exist., 422: The provided TOTP or backup code was incorrect., 500: Request was not successful} @endpoint DELETE /users/{user_id}/mfa @desc Disable a user's MFA methods @required {user_id: str # The ID of the user whose MFA methods are to be disabled} @returns(200) {user_id: str} # Successful operation. @errors {404: Resource not found, 500: Request was not successful} @endpoint DELETE /users/{user_id}/backup_code @desc Disable all user's Backup codes @required {user_id: str # The ID of the user whose backup codes are to be deleted.} @returns(200) {user_id: str} # Successful operation. @errors {404: Resource not found, 500: Request was not successful} @endpoint DELETE /users/{user_id}/passkeys/{passkey_identification_id} @desc Delete a user passkey @required {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} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {403: Authorization invalid, 404: Resource not found, 500: Request was not successful} @endpoint DELETE /users/{user_id}/web3_wallets/{web3_wallet_identification_id} @desc Delete a user web3 wallet @required {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} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found, 500: Request was not successful} @endpoint DELETE /users/{user_id}/totp @desc Delete all the user's TOTPs @required {user_id: str # The ID of the user whose TOTPs are to be deleted} @returns(200) {user_id: str} # Successful operation. @errors {404: Resource not found, 500: Request was not successful} @endpoint DELETE /users/{user_id}/external_accounts/{external_account_id} @desc Delete External Account @required {user_id: str # The ID of the user's external account, external_account_id: str # The ID of the external account to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 403: Request was not successful, 404: Resource not found, 500: Request was not successful} @endpoint POST /users/{user_id}/password/set_compromised @desc Set a user's password as compromised @required {user_id: str # The ID of the user to set the password as compromised} @optional {revoke_all_sessions: bool} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /users/{user_id}/password/unset_compromised @desc Unset a user's password as compromised @required {user_id: str # The ID of the user to unset the compromised status for} @returns(200) {id: str, object: str, external_id: str?, primary_email_address_id: str?, primary_phone_number_id: str?, primary_web3_wallet_id: str?, username: str?, first_name: str?, last_name: str?, locale: str?, profile_image_url: str, image_url: str, has_image: bool, public_metadata: map, private_metadata: map?, unsafe_metadata: map, email_addresses: [map], phone_numbers: [map], web3_wallets: [map], passkeys: [map], password_enabled: bool, two_factor_enabled: bool, totp_enabled: bool, backup_code_enabled: bool, mfa_enabled_at: int(int64)?, mfa_disabled_at: int(int64)?, password_last_updated_at: int(int64)?, external_accounts: [map], saml_accounts: [map], enterprise_accounts: [map], organization_memberships: [map], last_sign_in_at: int(int64)?, banned: bool, locked: bool, lockout_expires_in_seconds: int(int64)?, verification_attempts_remaining: int(int64)?, updated_at: int(int64), created_at: int(int64), delete_self_enabled: bool, create_organization_enabled: bool, create_organizations_limit: int?, last_active_at: int(int64)?, legal_accepted_at: int(int64)?, bypass_client_trust: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endgroup @group invitations @endpoint POST /invitations @desc Create an invitation @required {email_address: str # The email address the invitation will be sent to} @optional {public_metadata: map # Metadata that will be attached to the newly created invitation. The value of this property should be a well-formed JSON object. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata., redirect_url: str # Optional URL which specifies where to redirect the user once they click the invitation link. This is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you're not using Clerk Hosted Pages or Clerk Components., notify: bool=true # Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`., ignore_existing: bool=false # Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user., expires_in_days: int # The number of days the invitation will be valid for. By default, the invitation expires after 30 days., template_slug: str(invitation/waitlist_invitation) # The slug of the email template to use for the invitation email.} @returns(200) {object: str, id: str, email_address: str(email), public_metadata: map, revoked: bool, status: str, url: str, expires_at: int(int64)?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 422: Invalid request parameters} @endpoint GET /invitations @desc List all invitations @optional {status: str(pending/accepted/revoked/expired) # Filter invitations based on their status, query: str # Filter invitations based on their `email_address` or `id`, order_by: str=-created_at # Allows to return invitations in a particular order. At the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want invitations 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`., paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) List of invitations @endpoint POST /invitations/bulk @desc Create multiple invitations @returns(200) List of invitations @errors {400: Request was not successful, 422: Invalid request parameters} @endpoint POST /invitations/{invitation_id}/revoke @desc Revokes an invitation @required {invitation_id: str # The ID of the invitation to be revoked} @returns(200) Success @errors {400: Request was not successful, 404: Resource not found} @endgroup @group organization_invitations @endpoint GET /organization_invitations @desc Get a list of organization invitations for the current instance @optional {order_by: str=-created_at # Allows to return organization invitations in a particular order. At the moment, you can order the returned organization invitations either by their `created_at` or `email_address`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organization invitations 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`., status: str(pending/accepted/revoked/expired) # Filter organization invitations based on their status, query: str # Filter organization invitations based on their `email_address`, limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization invitations with public organization data @errors {400: Request was not successful, 404: Resource not found, 422: Request was not successful, 500: Request was not successful} @endgroup @group allowlist_identifiers @endpoint GET /allowlist_identifiers @desc List all identifiers on the allow-list @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) Success @errors {401: Authentication invalid, 402: Payment required} @endpoint POST /allowlist_identifiers @desc Add identifier to the allow-list @required {identifier: str # The identifier to be added in the allow-list. This can be an email address, a phone number, or a web3 wallet.} @optional {notify: bool=false # This flag denotes whether the given identifier will receive an invitation to join the application. Note that this only works for email address and phone number identifiers.} @returns(200) {object: str, id: str, invitation_id: str, identifier: str, identifier_type: str, instance_id: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 402: Payment required, 422: Invalid request parameters} @endpoint DELETE /allowlist_identifiers/{identifier_id} @desc Delete identifier from allow-list @required {identifier_id: str # The ID of the identifier to delete from the allow-list} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {402: Payment required, 404: Resource not found} @endgroup @group blocklist_identifiers @endpoint GET /blocklist_identifiers @desc List all identifiers on the block-list @returns(200) {data: [map], total_count: int(int64)} # Success @errors {401: Authentication invalid, 402: Payment required} @endpoint POST /blocklist_identifiers @desc Add identifier to the block-list @required {identifier: str # The identifier to be added in the block-list. This can be an email address, a phone number, or a web3 wallet.} @returns(200) {object: str, id: str, identifier: str, identifier_type: str, instance_id: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 402: Payment required, 422: Invalid request parameters} @endpoint DELETE /blocklist_identifiers/{identifier_id} @desc Delete identifier from block-list @required {identifier_id: str # The ID of the identifier to delete from the block-list} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {402: Payment required, 404: Resource not found} @endgroup @group beta_features @endpoint PATCH /beta_features/instance_settings @desc Update instance settings @optional {restricted_to_allowlist: bool=false # Whether sign up is restricted to email addresses, phone numbers and usernames that are on the allowlist., from_email_address: str # The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent. Only alphanumeric values are allowed. Note that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`)., progressive_sign_up: bool # Enable the Progressive Sign Up algorithm. This feature is deprecated, please contact support if you need assistance., test_mode: bool # Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances.} @returns(200) {object: str, id: str, restricted_to_allowlist: bool, from_email_address: str, progressive_sign_up: bool, enhanced_email_deliverability: bool} # InstanceSettings Server API @errors {402: Payment required, 422: Invalid request parameters} @endpoint PUT /beta_features/domain @desc Update production instance domain @optional {home_url: str # The new home URL of the production instance e.g. https://www.example.com, is_secondary: bool # Whether the domain is a secondary app.} @returns(202) Accepted @errors {400: Request was not successful, 422: Request was not successful} @endgroup @group actor_tokens @endpoint POST /actor_tokens @desc Create actor token @required {user_id: str # The ID of the user being impersonated., actor: map{sub!: str} # The actor payload. It needs to include a sub property which should contain the ID of the actor. This whole payload will be also included in the JWT session token.} @optional {expires_in_seconds: int=3600 # Optional parameter to specify the life duration of the actor token in seconds. By default, the duration is 1 hour., session_max_duration_in_seconds: int=1800 # The maximum duration that the session which will be created by the generated actor token should last. By default, the duration of a session created via an actor token, lasts 30 minutes.} @returns(200) {object: str, id: str, status: str, user_id: str, actor: map, token: str, url: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 402: Payment required, 422: Invalid request parameters} @endpoint POST /actor_tokens/{actor_token_id}/revoke @desc Revoke actor token @required {actor_token_id: str # The ID of the actor token to be revoked.} @returns(200) {object: str, id: str, status: str, user_id: str, actor: map, token: str, url: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 404: Resource not found} @endgroup @group domains @endpoint GET /domains @desc List all instance domains @returns(200) {data: [map], total_count: int(int64)} # A list of domains @endpoint POST /domains @desc Add a domain @required {name: str # The new domain name. Can contain the port for development instances., is_satellite: bool # Marks the new domain as satellite. Only `true` is accepted at the moment.} @optional {proxy_url: str # The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances.} @returns(200) {object: str, id: str, name: str, is_satellite: bool, frontend_api_url: str, accounts_portal_url: str?, proxy_url: str?, development_origin: str, cname_targets: [map]?} # A domain @errors {400: Request was not successful, 402: Request was not successful, 422: Invalid request parameters} @endpoint DELETE /domains/{domain_id} @desc Delete a satellite domain @required {domain_id: str # The ID of the domain that will be deleted. Must be a satellite domain.} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {403: Request was not successful, 404: Resource not found} @endpoint PATCH /domains/{domain_id} @desc Update a domain @required {domain_id: str # The ID of the domain that will be updated.} @optional {name: str # The new domain name. For development instances, can contain the port, i.e `myhostname:3000`. For production instances, must be a valid FQDN, i.e `mysite.com`. Cannot contain protocol scheme., proxy_url: str # The full URL of the proxy that will forward requests to Clerk's Frontend API. Can only be updated for production instances., is_secondary: bool # Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1).} @returns(200) {object: str, id: str, name: str, is_satellite: bool, frontend_api_url: str, accounts_portal_url: str?, proxy_url: str?, development_origin: str, cname_targets: [map]?} # A domain @errors {400: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endgroup @group instance @endpoint GET /instance @desc Fetch the current instance @returns(200) {object: str, id: str, environment_type: str, allowed_origins: [str]?} # Success @endpoint PATCH /instance @desc Update instance settings @optional {test_mode: bool # Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances., hibp: bool # Whether the instance should be using the HIBP service to check passwords for breaches, support_email: str, clerk_js_version: str, development_origin: str, allowed_origins: [str] # For browser-like stacks such as browser extensions, Electron (not officially supported), or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uuid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost., cookieless_dev: bool # Whether the instance should operate in cookieless development mode (i.e. without third-party cookies). Deprecated: Please use `url_based_session_syncing` instead., url_based_session_syncing: bool # Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies).} @returns(204) Accepted @errors {422: Invalid request parameters} @endpoint PATCH /instance/restrictions @desc Update instance restrictions @optional {allowlist: bool, blocklist: bool, allowlist_blocklist_disabled_on_sign_in: bool, block_email_subaddresses: bool, block_disposable_email_domains: bool} @returns(200) {object: str, allowlist: bool, blocklist: bool, allowlist_blocklist_disabled_on_sign_in: bool, block_email_subaddresses: bool, block_disposable_email_domains: bool} # Success @errors {402: Payment required, 422: Invalid request parameters} @endpoint GET /instance/protect @desc Get instance protect settings @returns(200) {object: str, rules_enabled: bool, specter_enabled: bool} # Success @endpoint PATCH /instance/protect @desc Update instance protect settings @optional {rules_enabled: bool, specter_enabled: bool} @returns(200) {object: str, rules_enabled: bool, specter_enabled: bool} # Success @errors {422: Invalid request parameters} @endpoint GET /instance/oauth_application_settings @desc Get OAuth application settings @returns(200) {object: str, dynamic_oauth_client_registration: bool, oauth_jwt_access_tokens: bool} # Success @endpoint PATCH /instance/oauth_application_settings @desc Update OAuth application settings @optional {dynamic_oauth_client_registration: bool # Whether dynamic OAuth client registration is enabled for the instance (RFC 7591)., oauth_jwt_access_tokens: bool # Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque access tokens).} @returns(200) {object: str, dynamic_oauth_client_registration: bool, oauth_jwt_access_tokens: bool} # Success @errors {422: Invalid request parameters} @endpoint POST /instance/change_domain @desc Update production instance domain @optional {home_url: str # The new home URL of the production instance e.g. https://www.example.com, is_secondary: bool # Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1).} @returns(202) Accepted @errors {400: Request was not successful, 422: Request was not successful} @endpoint PATCH /instance/organization_settings @desc Update instance organization settings @optional {enabled: bool, max_allowed_memberships: int, admin_delete_enabled: bool, domains_enabled: bool, slug_disabled: bool, domains_enrollment_modes: [str] # Specify which enrollment modes to enable for your Organization Domains. Supported modes are 'automatic_invitation' & 'automatic_suggestion'., creator_role_id: str # Specify what the default organization role is for an organization creator., domains_default_role_id: str # Specify what the default organization role is for the organization domains.} @returns(200) {object: str, enabled: bool, max_allowed_memberships: int, max_allowed_roles: int, max_role_sets_allowed: int, max_allowed_permissions: int, creator_role: str, admin_delete_enabled: bool, domains_enabled: bool, slug_disabled: bool, domains_enrollment_modes: [str], domains_default_role: str, initial_role_set_key: str?} # Success @errors {400: Request was not successful, 402: Payment required, 404: Resource not found, 422: Invalid request parameters} @endgroup @group webhooks @endpoint POST /webhooks/svix @desc Create a Svix app @returns(200) {svix_url: str} # Response that contains a temporary Svix URL to access management dashboard @errors {400: Request was not successful} @endpoint DELETE /webhooks/svix @desc Delete a Svix app @returns(204) Svix app was successfully deleted @errors {400: Request was not successful} @endpoint POST /webhooks/svix_url @desc Create a Svix Dashboard URL @returns(200) {svix_url: str} # Response that contains a temporary Svix URL to access management dashboard @errors {400: Request was not successful} @endgroup @group jwt_templates @endpoint GET /jwt_templates @desc List all templates @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) List of JWT templates @endpoint POST /jwt_templates @desc Create a JWT template @required {name: str # JWT template name, claims: map # JWT template claims in JSON format} @optional {lifetime: int # JWT lifetime, allowed_clock_skew: int # JWT allowed clock skew, custom_signing_key: bool # Whether a custom signing key/algorithm is also provided for this template, signing_algorithm: str # The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`., signing_key: str # The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`.} @returns(200) {object: str, id: str, name: str, claims: map, lifetime: int, allowed_clock_skew: int, custom_signing_key: bool, signing_algorithm: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 402: Payment required, 422: Invalid request parameters} @endpoint GET /jwt_templates/{template_id} @desc Retrieve a template @required {template_id: str # JWT Template ID} @returns(200) {object: str, id: str, name: str, claims: map, lifetime: int, allowed_clock_skew: int, custom_signing_key: bool, signing_algorithm: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {404: Resource not found} @endpoint PATCH /jwt_templates/{template_id} @desc Update a JWT template @required {template_id: str # The ID of the JWT template to update, name: str # JWT template name, claims: map # JWT template claims in JSON format} @optional {lifetime: int # JWT lifetime, allowed_clock_skew: int # JWT allowed clock skew, custom_signing_key: bool # Whether a custom signing key/algorithm is also provided for this template, signing_algorithm: str # The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`., signing_key: str # The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`.} @returns(200) {object: str, id: str, name: str, claims: map, lifetime: int, allowed_clock_skew: int, custom_signing_key: bool, signing_algorithm: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 402: Payment required, 422: Invalid request parameters} @endpoint DELETE /jwt_templates/{template_id} @desc Delete a Template @required {template_id: str # JWT Template ID} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {403: Authorization invalid, 404: Resource not found} @endgroup @group machines @endpoint GET /machines @desc Get a list of machines for an instance @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., query: str # Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name., order_by: str=-created_at # Allows to return machines in a particular order. You can order the returned machines by their `name` or `created_at`. To specify the direction, use the `+` or `-` symbols prepended to the property to order by. For example, to return machines in descending order by `created_at`, use `-created_at`. If you don't use `+` or `-`, then `+` is implied. Defaults to `-created_at`.} @returns(200) {data: [any], total_count: int} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /machines @desc Create a machine @required {name: str # The name of the machine} @optional {scoped_machines: [str] # Array of machine IDs that this machine will have access to. Maximum of 150 scopes per machine., default_token_ttl: int=3600 # The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 422: Invalid request parameters} @endpoint GET /machines/{machine_id} @desc Retrieve a machine @required {machine_id: str # The ID of the machine to retrieve} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint PATCH /machines/{machine_id} @desc Update a machine @required {machine_id: str # The ID of the machine to update} @optional {name: str # The name of the machine, default_token_ttl: int # The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.} @returns(200) Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /machines/{machine_id} @desc Delete a machine @required {machine_id: str # The ID of the machine to delete} @returns(200) {object: str, id: str, deleted: bool} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /machines/{machine_id}/secret_key @desc Retrieve a machine secret key @required {machine_id: str # The ID of the machine to retrieve the secret key for} @returns(200) {object: str, secret: str} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endpoint POST /machines/{machine_id}/secret_key/rotate @desc Rotate a machine's secret key @required {machine_id: str # The ID of the machine to rotate the secret key for, previous_token_ttl: int # The time in seconds that the previous secret key will remain valid after rotation. This ensures a graceful transition period for updating applications with the new secret key. Set to 0 to immediately expire the previous key. Maximum value is 8 hours (28800 seconds).} @returns(200) {object: str, secret: str} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /machines/{machine_id}/scopes @desc Create a machine scope @required {machine_id: str # The ID of the machine that will have access to another machine, to_machine_id: str # The ID of the machine that will be scoped to the current machine} @returns(200) {object: str, from_machine_id: str, to_machine_id: str, created_at: int(int64)} # Machine scope created successfully for a machine @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Conflict, 422: Invalid request parameters} @endpoint DELETE /machines/{machine_id}/scopes/{other_machine_id} @desc Delete a machine scope @required {machine_id: str # The ID of the machine that has access to another machine, other_machine_id: str # The ID of the machine that is being accessed} @returns(200) {object: str, from_machine_id: str, to_machine_id: str, deleted: bool} # Machine scope deleted successfully for a machine @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endgroup @group organizations @endpoint GET /organizations @desc Get a list of organizations for an instance @optional {include_members_count: bool # Flag to denote whether the member counts of each organization should be included in the response or not., include_missing_member_with_elevated_permissions: bool # Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization., query: str # 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., user_id: [str] # Returns organizations that include any of the specified user IDs as members. Any user IDs not found are ignored. For each user ID, the `+` and `-` can be prepended to the ID, which denote whether the respective organization should be included or excluded from the result set., organization_id: [str] # Returns organizations with the organization IDs specified. Any organization IDs not found are ignored. 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. Example: ?organization_id=+org_1&organization_id=-org_2, order_by: str=-created_at # 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`., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organizations @errors {400: Request was not successful, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /organizations @desc Create an organization @required {name: str # The name of the new organization. May not contain URLs or HTML. Max length: 256} @optional {created_by: str # The ID of the User who will become the administrator for the new organization, private_metadata: map # Metadata saved on the organization, accessible only from the Backend API, public_metadata: map # Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API, slug: str # A slug for the new organization. Can contain only lowercase alphanumeric characters and the dash "-". Must be unique for the instance. This field should only be included when slugs are enabled in the organization settings, refer to our [documentation](https://clerk.com/docs/guides/organizations/overview#organization-slugs)., max_allowed_memberships: int # The maximum number of memberships allowed for this organization, created_at: str # A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`)., role_set_key: str # The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.} @returns(200) {object: str, id: str, name: str, slug: str, image_url: str, has_image: bool, members_count: int, missing_member_with_elevated_permissions: bool, pending_invitations_count: int, max_allowed_memberships: int, admin_delete_enabled: bool, public_metadata: map, private_metadata: map, created_by: str, created_at: int(int64), updated_at: int(int64), last_active_at: int(int64), role_set_key: str?} # An organization @errors {400: Request was not successful, 402: Payment required, 403: Authorization invalid, 422: Invalid request parameters} @endpoint GET /organizations/{organization_id} @desc Retrieve an organization by ID or slug @required {organization_id: str # The ID or slug of the organization} @optional {include_members_count: bool # Flag to denote whether or not the organization's members count should be included in the response., include_missing_member_with_elevated_permissions: bool # Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.} @returns(200) {object: str, id: str, name: str, slug: str, image_url: str, has_image: bool, members_count: int, missing_member_with_elevated_permissions: bool, pending_invitations_count: int, max_allowed_memberships: int, admin_delete_enabled: bool, public_metadata: map, private_metadata: map, created_by: str, created_at: int(int64), updated_at: int(int64), last_active_at: int(int64), role_set_key: str?} # An organization @errors {403: Authorization invalid, 404: Resource not found} @endpoint PATCH /organizations/{organization_id} @desc Update an organization @required {organization_id: str # The ID of the organization to update} @optional {public_metadata: map # Metadata saved on the organization, that is visible to both your frontend and backend., private_metadata: map # Metadata saved on the organization that is only visible to your backend., name: str # The new name of the organization. May not contain URLs or HTML. Max length: 256, slug: str # The new slug of the organization, which needs to be unique in the instance, max_allowed_memberships: int # The maximum number of memberships allowed for this organization, admin_delete_enabled: bool # If true, an admin can delete this organization with the Frontend API., created_at: str # A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`)., role_set_key: str # The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.} @returns(200) {object: str, id: str, name: str, slug: str, image_url: str, has_image: bool, members_count: int, missing_member_with_elevated_permissions: bool, pending_invitations_count: int, max_allowed_memberships: int, admin_delete_enabled: bool, public_metadata: map, private_metadata: map, created_by: str, created_at: int(int64), updated_at: int(int64), last_active_at: int(int64), role_set_key: str?} # An organization @errors {400: Request was not successful, 402: Resource not found, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /organizations/{organization_id} @desc Delete an organization @required {organization_id: str # The ID of the organization to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {404: Resource not found} @endpoint PATCH /organizations/{organization_id}/metadata @desc Merge and update metadata for an organization @required {organization_id: str # The ID of the organization for which metadata will be merged or updated} @optional {public_metadata: map # Metadata saved on the organization, that is visible to both your frontend and backend. The new object will be merged with the existing value., private_metadata: map # Metadata saved on the organization that is only visible to your backend. The new object will be merged with the existing value.} @returns(200) {object: str, id: str, name: str, slug: str, image_url: str, has_image: bool, members_count: int, missing_member_with_elevated_permissions: bool, pending_invitations_count: int, max_allowed_memberships: int, admin_delete_enabled: bool, public_metadata: map, private_metadata: map, created_by: str, created_at: int(int64), updated_at: int(int64), last_active_at: int(int64), role_set_key: str?} # An organization @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint PUT /organizations/{organization_id}/logo @desc Upload a logo for the organization @required {organization_id: str # The ID of the organization for which to upload a logo} @returns(200) An organization with a logo URL. @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found, 413: Request was not successful} @endpoint DELETE /organizations/{organization_id}/logo @desc Delete the organization's logo. @required {organization_id: str # The ID of the organization for which the logo will be deleted.} @returns(200) {object: str, id: str, name: str, slug: str, image_url: str, has_image: bool, members_count: int, missing_member_with_elevated_permissions: bool, pending_invitations_count: int, max_allowed_memberships: int, admin_delete_enabled: bool, public_metadata: map, private_metadata: map, created_by: str, created_at: int(int64), updated_at: int(int64), last_active_at: int(int64), role_set_key: str?} # An organization @errors {404: Resource not found} @endpoint GET /organizations/{organization_id}/billing/subscription @desc Retrieve an organization's billing subscription @required {organization_id: str # The ID of the organization whose subscription to retrieve} @returns(200) {object: str, id: str, instance_id: str, status: str, payer_id: str, created_at: int(int64), updated_at: int(int64), active_at: int(int64)?, past_due_at: int(int64)?, subscription_items: [map], next_payment: map{date: int(int64), amount: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}}, eligible_for_free_trial: bool} # A commerce subscription. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /organizations/{organization_id}/billing/credits @desc Retrieve an organization's credit balance @required {organization_id: str # The ID of the organization whose credit balance to retrieve} @returns(200) {object: str, balance: any?} # A payer's credit balance. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint POST /organizations/{organization_id}/billing/credits @desc Adjust an organization's credit balance @required {organization_id: str # The ID of the organization whose credit balance to adjust, amount: int(int64) # The credit amount in cents. Must be greater than zero., action: str(increase/decrease) # Whether to increase or decrease the credit balance., idempotency_key: str # A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry.} @optional {currency: str # The currency code (e.g. "USD"). Defaults to USD if not provided., note: str # An optional note to attach to the ledger entry.} @returns(200) {object: str, id: str, payer_id: str, amount: int(int64), currency: str, source_type: str, source_id: str, note: str?, created_at: str(date-time)} # A credit ledger entry. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Request was not successful, 422: Invalid request parameters, 500: Request was not successful} @endpoint POST /organizations/{organization_id}/invitations @desc Create and send an organization invitation @required {organization_id: str # The ID of the organization for which to send the invitation, email_address: str # The email address of the new member that is going to be invited to the organization, role: str # The role of the new member in the organization} @optional {inviter_user_id: str # The ID of the user that invites the new member to the organization. Must be an administrator in the organization., public_metadata: map # Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership., private_metadata: map # Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership., redirect_url: str # Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email., expires_in_days: int # The number of days the invitation will be valid for. By default, the invitation has a 30 days expire., notify: bool=true # Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.} @returns(200) {object: str, id: str, email_address: str, role: str, role_name: str, organization_id: str, inviter_id: str?, public_inviter_data: map?{user_id: str, first_name: str?, last_name: str?, image_url: str, has_image: bool, identifier: str}, status: str, public_metadata: map, private_metadata: map, url: str?, expires_at: int(int64)?, created_at: int(int64), updated_at: int(int64)} # An organization invitation @errors {400: Request was not successful, 402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /organizations/{organization_id}/invitations @desc Get a list of organization invitations @required {organization_id: str # The organization ID.} @optional {status: str(pending/accepted/revoked/expired) # Filter organization invitations based on their status, email_address: str # Returns organization invitations inviting the specified email address., order_by: str=-created_at # Allows to return organization invitations in a particular order. You can order the returned organization invitations either by their `created_at` or `email_address`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organization invitations 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`., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization invitations @errors {400: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /organizations/{organization_id}/invitations/bulk @desc Bulk create and send organization invitations @required {organization_id: str # The organization ID.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization invitations @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /organizations/{organization_id}/invitations/pending @desc Get a list of pending organization invitations @required {organization_id: str # The organization ID.} @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization invitations @errors {400: Request was not successful, 404: Resource not found} @endpoint GET /organizations/{organization_id}/invitations/{invitation_id} @desc Retrieve an organization invitation by ID @required {organization_id: str # The organization ID., invitation_id: str # The organization invitation ID.} @returns(200) {object: str, id: str, email_address: str, role: str, role_name: str, organization_id: str, inviter_id: str?, public_inviter_data: map?{user_id: str, first_name: str?, last_name: str?, image_url: str, has_image: bool, identifier: str}, status: str, public_metadata: map, private_metadata: map, url: str?, expires_at: int(int64)?, created_at: int(int64), updated_at: int(int64)} # An organization invitation @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found} @endpoint POST /organizations/{organization_id}/invitations/{invitation_id}/revoke @desc Revoke a pending organization invitation @required {organization_id: str # The organization ID., invitation_id: str # The organization invitation ID.} @optional {requesting_user_id: str # The ID of the user that revokes the invitation. Must be an administrator in the organization.} @returns(200) {object: str, id: str, email_address: str, role: str, role_name: str, organization_id: str, inviter_id: str?, public_inviter_data: map?{user_id: str, first_name: str?, last_name: str?, image_url: str, has_image: bool, identifier: str}, status: str, public_metadata: map, private_metadata: map, url: str?, expires_at: int(int64)?, created_at: int(int64), updated_at: int(int64)} # An organization invitation @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found} @endgroup @group organization_roles @endpoint GET /organization_roles @desc Get a list of organization roles @optional {query: str # Returns organization roles with ID, name, or key that match the given query. Uses exact match for organization role ID and partial match for name and key., order_by: str=-created_at # Allows to return organization roles in a particular order. At the moment, you can order the returned organization roles by their `created_at`, `name`, or `key`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organization roles 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`., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /organization_roles @desc Create an organization role @required {name: str # The name of the new organization role, key: str # A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores.} @optional {description: str # Optional description for the role, permissions: [str] # Array of permission IDs to assign to the role, include_in_initial_role_set: bool # Whether this role should be included in the initial role set} @returns(200) {object: str, id: str, name: str, key: str, description: str?, is_creator_eligible: bool, permissions: [map], created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /organization_roles/{organization_role_id} @desc Retrieve an organization role @required {organization_role_id: str # The ID of the organization role} @returns(200) {object: str, id: str, name: str, key: str, description: str?, is_creator_eligible: bool, permissions: [map], created_at: int(int64), updated_at: int(int64)} # Success @errors {401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endpoint PATCH /organization_roles/{organization_role_id} @desc Update an organization role @required {organization_role_id: str # The ID of the organization role to update} @optional {name: str # The new name for the organization role, key: str # A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores., description: str # Optional description for the role, permissions: [str] # Array of permission IDs to assign to the role. If provided, this will replace the existing permissions.} @returns(200) {object: str, id: str, name: str, key: str, description: str?, is_creator_eligible: bool, permissions: [map], created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /organization_roles/{organization_role_id} @desc Delete an organization role @required {organization_role_id: str # The ID of the organization role to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /organization_roles/{organization_role_id}/permissions/{permission_id} @desc Assign a permission to an organization role @required {organization_role_id: str # The ID of the organization role, permission_id: str # The ID of the permission to assign} @returns(200) {object: str, id: str, name: str, key: str, description: str?, is_creator_eligible: bool, permissions: [map], created_at: int(int64), updated_at: int(int64)} # Success @errors {401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Conflict} @endpoint DELETE /organization_roles/{organization_role_id}/permissions/{permission_id} @desc Remove a permission from an organization role @required {organization_role_id: str # The ID of the organization role, permission_id: str # The ID of the permission to remove} @returns(200) {object: str, id: str, name: str, key: str, description: str?, is_creator_eligible: bool, permissions: [map], created_at: int(int64), updated_at: int(int64)} # Success @errors {401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endgroup @group organizations @endpoint POST /organizations/{organization_id}/memberships @desc Create a new organization membership @required {organization_id: str # The ID of the organization where the new membership will be created, user_id: str # The ID of the user that will be added as a member in the organization. The user needs to exist in the same instance as the organization and must not be a member of the given organization already., role: str # The role that the new member will have in the organization.} @optional {public_metadata: map # Metadata saved on the organization membership, that is visible to both your frontend and backend., private_metadata: map # Metadata saved on the organization membership that is only visible to your backend.} @returns(200) {id: str, object: str, role: str, role_name: str, permissions: [str], public_metadata: map, private_metadata: map, organization: map, public_user_data: map{user_id: str, first_name: str?, last_name: str?, profile_image_url: str?, image_url: str, has_image: bool, identifier: str?, username: str?}, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /organizations/{organization_id}/memberships @desc Get a list of all members of an organization @required {organization_id: str # The organization ID.} @optional {order_by: str # Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.", user_id: [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., email_address: [str] # Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored., phone_number: [str] # Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored., username: [str] # Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored., web3_wallet: [str] # Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addresses not found are ignored., role: [str] # Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored., query: 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., email_address_query: str # Returns users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`., phone_number_query: str # Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`., username_query: str # Returns users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`., name_query: str # Returns users with names that match the given query, via case-insensitive partial match., last_active_at_before: int # 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., last_active_at_after: int # 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., created_at_before: int # 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., created_at_after: int # 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., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization memberships @errors {401: Authentication invalid, 422: Invalid request parameters} @endpoint PATCH /organizations/{organization_id}/memberships/{user_id} @desc Update an organization membership @required {organization_id: str # The ID of the organization to which this membership belongs, user_id: str # The ID of the user to which this membership belongs, role: str # The new role of the given membership.} @returns(200) {id: str, object: str, role: str, role_name: str, permissions: [str], public_metadata: map, private_metadata: map, organization: map, public_user_data: map{user_id: str, first_name: str?, last_name: str?, profile_image_url: str?, image_url: str, has_image: bool, identifier: str?, username: str?}, created_at: int(int64), updated_at: int(int64)} # Success @errors {404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /organizations/{organization_id}/memberships/{user_id} @desc Remove a member from an organization @required {organization_id: str # The ID of the organization to which this membership belongs, user_id: str # The ID of the user to which this membership belongs} @returns(200) {id: str, object: str, role: str, role_name: str, permissions: [str], public_metadata: map, private_metadata: map, organization: map, public_user_data: map{user_id: str, first_name: str?, last_name: str?, profile_image_url: str?, image_url: str, has_image: bool, identifier: str?, username: str?}, created_at: int(int64), updated_at: int(int64)} # Success @errors {401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint PATCH /organizations/{organization_id}/memberships/{user_id}/metadata @desc Merge and update organization membership metadata @required {organization_id: str # The ID of the organization to which this membership belongs, user_id: str # The ID of the user to which this membership belongs} @optional {public_metadata: map # Metadata saved on the organization membership, that is visible to both your frontend and backend. The new object will be merged with the existing value., private_metadata: map # Metadata saved on the organization membership that is only visible to your backend. The new object will be merged with the existing value.} @returns(200) {id: str, object: str, role: str, role_name: str, permissions: [str], public_metadata: map, private_metadata: map, organization: map, public_user_data: map{user_id: str, first_name: str?, last_name: str?, profile_image_url: str?, image_url: str, has_image: bool, identifier: str?, username: str?}, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /organizations/{organization_id}/domains @desc Create a new organization domain. @required {organization_id: str # The ID of the organization where the new domain will be created.} @optional {name: str # The name of the new domain, enrollment_mode: str # The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation`, verified: bool # The status of domain's verification. Defaults to true} @returns(200) {object: str, id: str, organization_id: str, name: str, enrollment_mode: str, affiliation_email_address: str?, verification: map?, total_pending_invitations: int(int32), total_pending_suggestions: int(int32), public_organization_data: map?, created_at: int(int64), updated_at: int(int64)} # An organization domain @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /organizations/{organization_id}/domains @desc Get a list of all domains of an organization. @required {organization_id: str # The organization ID.} @optional {verified: str # Filter domains by their verification status. `true` or `false`, enrollment_mode: str # Filter domains by their enrollment mode, limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization domains @errors {401: Authentication invalid, 422: Invalid request parameters} @endpoint PATCH /organizations/{organization_id}/domains/{domain_id} @desc Update an organization domain. @required {organization_id: str # The ID of the organization to which the domain belongs, domain_id: str # The ID of the domain} @optional {enrollment_mode: str # The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation`, verified: bool # The status of the domain's verification} @returns(200) {object: str, id: str, organization_id: str, name: str, enrollment_mode: str, affiliation_email_address: str?, verification: map?, total_pending_invitations: int(int32), total_pending_suggestions: int(int32), public_organization_data: map?, created_at: int(int64), updated_at: int(int64)} # An organization domain @errors {400: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /organizations/{organization_id}/domains/{domain_id} @desc Remove a domain from an organization. @required {organization_id: str # The ID of the organization to which the domain belongs, domain_id: str # The ID of the domain} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found} @endgroup @group organization_domains @endpoint GET /organization_domains @desc List all organization domains @optional {organization_id: str # The ID of the organization to filter domains by, verified: str(true/false) # Filter by verification status, enrollment_mode: [str] # Filter by enrollment mode, query: str # Search domains by name or organization ID. If the query starts with "org_", it will search by exact organization ID match. Otherwise, it performs a case-insensitive partial match on the domain name. Note: An empty string or whitespace-only value is not allowed and will result in a validation error., domains: [str] # Filter by exact domain names. Accepts multiple values (e.g. domains=example.com&domains=test.org)., order_by: str=-created_at # Allows to return organization domains in a particular order. At the moment, you can order the returned domains by their `name` or `created_at`. In order to specify the direction, you can use the `+/-` symbols prepended to the property to order by. For example, if you want domains 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`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization domains @errors {401: Authentication invalid, 403: Authorization invalid, 422: Invalid request parameters} @endgroup @group proxy_checks @endpoint POST /proxy_checks @desc Verify the proxy configuration for your domain @optional {domain_id: str # The ID of the domain that will be updated., proxy_url: str # The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. e.g. https://example.com/__clerk} @returns(200) {object: str, id: str, domain_id: str, last_run_at: int(int64)?, proxy_url: str, successful: bool, created_at: int(int64), updated_at: int(int64)} # Health check information about a domain's proxy configuration validation attempt. @errors {400: Request was not successful, 422: Invalid request parameters} @endgroup @group redirect_urls @endpoint GET /redirect_urls @desc List all redirect URLs @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) List of Redirect URLs @endpoint POST /redirect_urls @desc Create a redirect URL @required {url: str # The full URL value prefixed with `https://` or a custom scheme e.g. `"https://my-app.com/oauth-callback"` or `"my-app://oauth-callback"`} @returns(200) {object: str, id: str, url: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 422: Invalid request parameters} @endpoint GET /redirect_urls/{id} @desc Retrieve a redirect URL @required {id: str # The ID of the redirect URL} @returns(200) {object: str, id: str, url: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {404: Resource not found} @endpoint DELETE /redirect_urls/{id} @desc Delete a redirect URL @required {id: str # The ID of the redirect URL} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {404: Resource not found} @endgroup @group sign_in_tokens @endpoint POST /sign_in_tokens @desc Create sign-in token @required {user_id: str # The ID of the user that can use the newly created sign in token} @optional {expires_in_seconds: int=2592000 # Optional parameter to specify the life duration of the sign in token in seconds. By default, the duration is 30 days.} @returns(200) {object: str, id: str, status: str, user_id: str, token: str, url: str?, created_at: int(int64), updated_at: int(int64)} # Success @errors {404: Resource not found, 422: Invalid request parameters} @endpoint POST /sign_in_tokens/{sign_in_token_id}/revoke @desc Revoke the given sign-in token @required {sign_in_token_id: str # The ID of the sign-in token to be revoked} @returns(200) {object: str, id: str, status: str, user_id: str, token: str, url: str?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 404: Resource not found} @endgroup @group sign_ups @endpoint GET /sign_ups/{id} @desc Retrieve a sign-up by ID @required {id: str # The ID of the sign-up to retrieve} @returns(200) {object: str, id: str, status: str, required_fields: [str], optional_fields: [str], missing_fields: [str], unverified_fields: [str], verifications: map{email_address: map?{next_action: str, supported_strategies: [str]}, phone_number: map?{next_action: str, supported_strategies: [str]}, web3_wallet: map?{next_action: str, supported_strategies: [str]}, external_account: map?}, username: str?, email_address: str?, phone_number: str?, web3_wallet: str?, password_enabled: bool, first_name: str?, last_name: str?, unsafe_metadata: map, public_metadata: map, custom_action: bool, external_id: str?, created_session_id: str?, created_user_id: str?, abandon_at: int(int64), legal_accepted_at: int(int64)?, locale: str?, external_account: map} # Success @errors {403: Authorization invalid} @endpoint PATCH /sign_ups/{id} @desc Update a sign-up @required {id: str # The ID of the sign-up to update} @optional {external_id: str # The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution. This will be copied to the resulting user when the sign-up is completed., custom_action: bool # If true, the sign-up will be marked as a custom action.} @returns(200) {object: str, id: str, status: str, required_fields: [str], optional_fields: [str], missing_fields: [str], unverified_fields: [str], verifications: map{email_address: map?{next_action: str, supported_strategies: [str]}, phone_number: map?{next_action: str, supported_strategies: [str]}, web3_wallet: map?{next_action: str, supported_strategies: [str]}, external_account: map?}, username: str?, email_address: str?, phone_number: str?, web3_wallet: str?, password_enabled: bool, first_name: str?, last_name: str?, unsafe_metadata: map, public_metadata: map, custom_action: bool, external_id: str?, created_session_id: str?, created_user_id: str?, abandon_at: int(int64), legal_accepted_at: int(int64)?, locale: str?, external_account: map} # Success @errors {403: Authorization invalid} @endgroup @group oauth_applications @endpoint GET /oauth_applications @desc Get a list of OAuth applications for an instance @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., order_by: str=+created_at # Allows to return OAuth applications in a particular order. At the moment, you can order the returned OAuth applications by their `created_at` and `name`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want OAuth applications 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=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case., name_query: str # Returns OAuth applications with names that match the given query, via case-insensitive partial match.} @returns(200) {data: [map], total_count: int(int64)} # A list of OAuth applications @errors {400: Request was not successful, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /oauth_applications @desc Create an OAuth application @required {name: str # The name of the new OAuth application. Max length: 256} @optional {redirect_uris: [str] # An array of redirect URIs of the new OAuth application, callback_url: str # The callback URL of the new OAuth application, scopes: str=profile email # Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces., consent_screen_enabled: bool=true # True to enable a consent screen to display in the authentication flow., pkce_required: bool=false # True to require the Proof Key of Code Exchange (PKCE) flow., public: bool # If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.} @returns(200) An OAuth application with client secret @errors {400: Request was not successful, 403: Authorization invalid, 422: Invalid request parameters} @endpoint GET /oauth_applications/{oauth_application_id} @desc Retrieve an OAuth application by ID @required {oauth_application_id: str # The ID of the OAuth application} @returns(200) {object: str, id: str, instance_id: str, name: str, client_id: str, client_uri: str?, client_image_url: str?, dynamically_registered: bool, consent_screen_enabled: bool, pkce_required: bool, public: bool, scopes: str, redirect_uris: [str], callback_url: str, authorize_url: str, token_fetch_url: str, user_info_url: str, discovery_url: str, token_introspection_url: str, created_at: int(int64), updated_at: int(int64)} # An OAuth application @errors {403: Authorization invalid, 404: Resource not found} @endpoint PATCH /oauth_applications/{oauth_application_id} @desc Update an OAuth application @required {oauth_application_id: str # The ID of the OAuth application to update} @optional {name: str # The new name of the OAuth application. Max length: 256, redirect_uris: [str] # An array of redirect URIs of the new OAuth application, callback_url: str # The new callback URL of the OAuth application, scopes: str=profile email # Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces., consent_screen_enabled: bool # True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications., pkce_required: bool # True to require the Proof Key of Code Exchange (PKCE) flow., public: bool # If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.} @returns(200) {object: str, id: str, instance_id: str, name: str, client_id: str, client_uri: str?, client_image_url: str?, dynamically_registered: bool, consent_screen_enabled: bool, pkce_required: bool, public: bool, scopes: str, redirect_uris: [str], callback_url: str, authorize_url: str, token_fetch_url: str, user_info_url: str, discovery_url: str, token_introspection_url: str, created_at: int(int64), updated_at: int(int64)} # An OAuth application @errors {400: Request was not successful, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /oauth_applications/{oauth_application_id} @desc Delete an OAuth application @required {oauth_application_id: str # The ID of the OAuth application to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {403: Authorization invalid, 404: Resource not found} @endpoint POST /oauth_applications/{oauth_application_id}/rotate_secret @desc Rotate the client secret of the given OAuth application @required {oauth_application_id: str # The ID of the OAuth application for which to rotate the client secret} @returns(200) An OAuth application with client secret @errors {403: Authorization invalid, 404: Resource not found} @endgroup @group saml_connections @endpoint GET /saml_connections @desc Get a list of SAML Connections for an instance @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., query: str # Returns SAML connections that have a name that matches the given query, via case-insensitive partial match., order_by: str # Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order., organization_id: [str] # Returns SAML connections that have an associated organization ID 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.} @returns(200) {data: [map], total_count: int(int64)} # A list of SAML Connections @errors {402: Payment required, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /saml_connections @desc Create a SAML Connection @required {name: str # The name to use as a label for this SAML Connection, provider: str(saml_custom/saml_okta/saml_google/saml_microsoft) # The IdP provider of the connection.} @optional {domain: str # The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection., domains: [str] # The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection., idp_entity_id: str # The Entity ID as provided by the IdP, idp_sso_url: str # The Single-Sign On URL as provided by the IdP, idp_certificate: str # The X.509 certificate as provided by the IdP, idp_metadata_url: str # The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties, idp_metadata: str # The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties, organization_id: str # The ID of the organization to which users of this SAML Connection will be added, attribute_mapping: map{user_id: str, email_address: str, first_name: str, last_name: str} # Define the attribute name mapping between Identity Provider and Clerk's user properties, force_authn: bool # Enable or deactivate ForceAuthn} @returns(200) {object: str, id: str, name: str, domain: str, domains: [str], idp_entity_id: str?, idp_sso_url: str?, idp_certificate: str?, idp_metadata_url: str?, idp_metadata: str?, acs_url: str, sp_entity_id: str, sp_metadata_url: str, organization_id: str?, attribute_mapping: map{user_id: str, email_address: str, first_name: str, last_name: str}, active: bool, provider: str, user_count: int, sync_user_attributes: bool, allow_subdomains: bool, allow_idp_initiated: bool, disable_additional_identifications: bool, allow_organization_account_linking: bool, force_authn: bool, enterprise_connection_id: str?, created_at: int(int64), updated_at: int(int64)} # A SAML Connection @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /saml_connections/{saml_connection_id} @desc Retrieve a SAML Connection by ID @required {saml_connection_id: str # The ID of the SAML Connection} @returns(200) {object: str, id: str, name: str, domain: str, domains: [str], idp_entity_id: str?, idp_sso_url: str?, idp_certificate: str?, idp_metadata_url: str?, idp_metadata: str?, acs_url: str, sp_entity_id: str, sp_metadata_url: str, organization_id: str?, attribute_mapping: map{user_id: str, email_address: str, first_name: str, last_name: str}, active: bool, provider: str, user_count: int, sync_user_attributes: bool, allow_subdomains: bool, allow_idp_initiated: bool, disable_additional_identifications: bool, allow_organization_account_linking: bool, force_authn: bool, enterprise_connection_id: str?, created_at: int(int64), updated_at: int(int64)} # A SAML Connection @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found} @endpoint PATCH /saml_connections/{saml_connection_id} @desc Update a SAML Connection @required {saml_connection_id: str # The ID of the SAML Connection to update} @optional {name: str # The name of the new SAML Connection, domain: str # The domain to use for the new SAML Connection, domains: [str] # A list of the domains on use for the SAML connection, idp_entity_id: str # The Entity ID as provided by the IdP, idp_sso_url: str # The SSO URL as provided by the IdP, idp_certificate: str # The x509 certificated as provided by the IdP, idp_metadata_url: str # The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them, idp_metadata: str # The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties, organization_id: str # The ID of the organization to which users of this SAML Connection will be added, attribute_mapping: map{user_id: str, email_address: str, first_name: str, last_name: str} # Define the attribute name mapping between Identity Provider and Clerk's user properties, active: bool # Activate or de-activate the SAML Connection, sync_user_attributes: bool # Controls whether to update the user's attributes in each sign-in, allow_subdomains: bool # Allow users with an email address subdomain to use this connection in order to authenticate, allow_idp_initiated: bool # Enable or deactivate IdP-initiated flows, disable_additional_identifications: bool # Enable or deactivate additional identifications, allow_organization_account_linking: bool # Whether this connection supports account linking via organization membership, force_authn: bool # Enable or deactivate ForceAuthn, consent_verified_domains_deletion: bool # When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.} @returns(200) {object: str, id: str, name: str, domain: str, domains: [str], idp_entity_id: str?, idp_sso_url: str?, idp_certificate: str?, idp_metadata_url: str?, idp_metadata: str?, acs_url: str, sp_entity_id: str, sp_metadata_url: str, organization_id: str?, attribute_mapping: map{user_id: str, email_address: str, first_name: str, last_name: str}, active: bool, provider: str, user_count: int, sync_user_attributes: bool, allow_subdomains: bool, allow_idp_initiated: bool, disable_additional_identifications: bool, allow_organization_account_linking: bool, force_authn: bool, enterprise_connection_id: str?, created_at: int(int64), updated_at: int(int64)} # A SAML Connection @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /saml_connections/{saml_connection_id} @desc Delete a SAML Connection @required {saml_connection_id: str # The ID of the SAML Connection to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found} @endgroup @group enterprise_connections @endpoint GET /enterprise_connections @desc List enterprise connections @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., organization_id: str # Filter enterprise connections by organization ID, active: bool # Filter by active status. If true, only active connections are returned. If false, only inactive connections are returned. If omitted, all connections are returned.} @returns(200) {data: [map], total_count: int(int64)} # A list of enterprise connections @errors {402: Payment required, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /enterprise_connections @desc Create an enterprise connection @required {name: str # The display name of the connection, provider: str(saml_custom/saml_okta/saml_google/saml_microsoft/oidc_custom/oidc_github_enterprise/oidc_gitlab) # The identity provider (e.g. saml_custom, oidc_custom, oidc_github_enterprise, oidc_gitlab), domains: [str] # Domains associated with the enterprise connection (required; at least one). Values are normalized to lowercase. Each domain must be a valid fully qualified domain name.} @optional {organization_id: str # Organization ID when the connection is linked to an organization, allow_organization_account_linking: bool # Whether this connection supports account linking via organization membership, active: bool # Whether the enterprise connection is active. When true, IdP metadata must be provided via the `saml` object., saml: map{idp_entity_id: str, idp_sso_url: str, idp_certificate: str, idp_metadata_url: str, idp_metadata: str, attribute_mapping: map, allow_subdomains: bool, allow_idp_initiated: bool, force_authn: bool} # SAML connection-specific properties. Only applied when the enterprise connection uses SAML (e.g. provider is saml_custom). Use this to set IdP configuration, attribute mapping, and other SAML-specific settings at creation time., oidc: map{client_id: str, client_secret: str, discovery_url: str, auth_url: str, token_url: str, user_info_url: str, requires_pkce: bool} # OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. provider is oidc_custom, oidc_github_enterprise, or oidc_gitlab)., custom_attributes: [map{name!: str, key!: str, sso_path: str, scim_path: str}] # Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning. Requires the custom attributes feature to be enabled for the instance.} @returns(201) {id: str, name: str, active: bool, domains: [str], organization_id: str?, sync_user_attributes: bool, disable_additional_identifications: bool, allow_organization_account_linking: bool, custom_attributes: [map], saml_connection: map?{id: str, name: str, idp_entity_id: str?, idp_sso_url: str?, idp_metadata_url: str?, acs_url: str?, sp_entity_id: str?, sp_metadata_url: str?, active: bool, allow_idp_initiated: bool, allow_subdomains: bool, force_authn: bool}, oauth_config: map?{id: str, name: str, provider_key: str, client_id: str?, discovery_url: str?, logo_public_url: str?, created_at: int(int64), updated_at: int(int64)}, created_at: int(int64), updated_at: int(int64)} # An enterprise connection @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /enterprise_connections/{enterprise_connection_id} @desc Retrieve an enterprise connection @required {enterprise_connection_id: str # The ID of the enterprise connection} @returns(200) {id: str, name: str, active: bool, domains: [str], organization_id: str?, sync_user_attributes: bool, disable_additional_identifications: bool, allow_organization_account_linking: bool, custom_attributes: [map], saml_connection: map?{id: str, name: str, idp_entity_id: str?, idp_sso_url: str?, idp_metadata_url: str?, acs_url: str?, sp_entity_id: str?, sp_metadata_url: str?, active: bool, allow_idp_initiated: bool, allow_subdomains: bool, force_authn: bool}, oauth_config: map?{id: str, name: str, provider_key: str, client_id: str?, discovery_url: str?, logo_public_url: str?, created_at: int(int64), updated_at: int(int64)}, created_at: int(int64), updated_at: int(int64)} # An enterprise connection @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found} @endpoint PATCH /enterprise_connections/{enterprise_connection_id} @desc Update an enterprise connection @required {enterprise_connection_id: str # The ID of the enterprise connection to update} @optional {name: str # The display name of the enterprise connection, domains: [str] # Domains associated with the enterprise connection. Values are normalized to lowercase. Empty array means ignored (no change); non-empty array means set domains to the given list (replaces existing)., active: bool # Whether the enterprise connection is active. When set to true (enabling), any existing verified organization domains for the same domain(s) will be removed so the connection can be enabled., sync_user_attributes: bool # Whether to sync user attributes on sign-in, disable_additional_identifications: bool # Whether to disable additional identifications, allow_organization_account_linking: bool # Whether this connection supports account linking via organization membership, organization_id: str # Organization ID to link to this enterprise connection. Only linking is supported; sending this field sets or changes the linked organization. There is no way to unlink an organization once linked., saml: map{name: str, idp_entity_id: str, idp_sso_url: str, idp_certificate: str, idp_metadata_url: str, idp_metadata: str, attribute_mapping: map, allow_subdomains: bool, allow_idp_initiated: bool, force_authn: bool} # SAML connection-specific properties. Only applied when the enterprise connection uses SAML. Use this to update IdP configuration, attribute mapping, and other SAML-specific settings., oidc: map{client_id: str, client_secret: str, discovery_url: str, auth_url: str, token_url: str, user_info_url: str, requires_pkce: bool} # OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. oidc_custom, oidc_github_enterprise, or oidc_gitlab)., custom_attributes: [map{name!: str, key!: str, sso_path: str, scim_path: str}] # Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning. Requires the custom attributes feature to be enabled for the instance.} @returns(200) {id: str, name: str, active: bool, domains: [str], organization_id: str?, sync_user_attributes: bool, disable_additional_identifications: bool, allow_organization_account_linking: bool, custom_attributes: [map], saml_connection: map?{id: str, name: str, idp_entity_id: str?, idp_sso_url: str?, idp_metadata_url: str?, acs_url: str?, sp_entity_id: str?, sp_metadata_url: str?, active: bool, allow_idp_initiated: bool, allow_subdomains: bool, force_authn: bool}, oauth_config: map?{id: str, name: str, provider_key: str, client_id: str?, discovery_url: str?, logo_public_url: str?, created_at: int(int64), updated_at: int(int64)}, created_at: int(int64), updated_at: int(int64)} # An enterprise connection @errors {400: Request was not successful, 402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /enterprise_connections/{enterprise_connection_id} @desc Delete an enterprise connection @required {enterprise_connection_id: str # The ID of the enterprise connection to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {402: Payment required, 403: Authorization invalid, 404: Resource not found} @endgroup @group testing_tokens @endpoint POST /testing_tokens @desc Retrieve a new testing token @returns(200) {object: str, token: str, expires_at: int(int64)} # A Testing Token @endgroup @group agents @endpoint POST /agents/tasks @desc Create agent task @required {on_behalf_of: map{user_id: str, identifier: str} # Identifies the user on whose behalf the agent task is created. Exactly one of user_id or identifier must be provided., permissions: str # The permissions granted to the agent task. Must be "*" (all permissions)., agent_name: str # A name identifying the agent. Used to derive a stable agent_id per instance. Logged for audit purposes., task_description: str # A description of the task being performed. Logged for audit purposes., redirect_url: str(uri) # The URL the user is redirected to after the agent task is accepted. Must be a valid absolute URL with an `https` scheme in production instances. In development instances, `http` is also permitted. The URL's domain must belong to one of the instance's associated domains (primary or satellite); otherwise the redirect will be rejected when the task ticket is consumed.} @optional {session_max_duration_in_seconds: int=1800 # The maximum duration that the session which will be created by the generated agent task should last. By default, the duration of a session created via an agent task lasts 30 minutes.} @returns(200) {object: str, agent_id: str, agent_task_id: str, task_id: str, url: str} # Success @errors {400: Request was not successful, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /agents/tasks/{agent_task_id}/revoke @desc Revoke agent task @required {agent_task_id: str # The ID of the agent task to be revoked.} @returns(200) {object: str, agent_id: str, agent_task_id: str, task_id: str, url: str} # Success @errors {400: Request was not successful, 404: Resource not found} @endgroup @group organization_memberships @endpoint GET /organization_memberships @desc Get a list of all organization memberships within an instance. @optional {order_by: str # Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of organization memberships @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters, 500: Request was not successful} @endgroup @group waitlist_entries @endpoint GET /waitlist_entries @desc List all waitlist entries @optional {limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., query: str # Filter waitlist entries by `email_address` or `id`, status: str(pending/invited/completed/rejected) # Filter waitlist entries by their status, order_by: str=-created_at # Specify the order of results. Supported values are: - `created_at` - `email_address` - `invited_at` Use `+` for ascending or `-` for descending order. Defaults to `-created_at`.} @returns(200) {data: [map], total_count: int} # List of waitlist entries @endpoint POST /waitlist_entries @desc Create a waitlist entry @required {email_address: str # The email address to add to the waitlist} @optional {notify: bool=true # Optional flag which denotes whether a confirmation email should be sent to the given email address. Defaults to `true`.} @returns(200) {object: str, id: str, email_address: str(email), status: str, is_locked: bool, created_at: int(int64), updated_at: int(int64), invitation: map?} # A Waitlist Entry @errors {400: Request was not successful, 422: Invalid request parameters} @endpoint POST /waitlist_entries/bulk @desc Create multiple waitlist entries @returns(200) Array of waitlist entries @errors {400: Request was not successful, 422: Invalid request parameters} @endpoint DELETE /waitlist_entries/{waitlist_entry_id} @desc Delete a pending waitlist entry @required {waitlist_entry_id: str # The ID of the waitlist entry to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 404: Resource not found, 409: Conflict, 422: Invalid request parameters} @endpoint POST /waitlist_entries/{waitlist_entry_id}/invite @desc Invite a waitlist entry @required {waitlist_entry_id: str # The ID of the waitlist entry to invite} @optional {ignore_existing: bool=false # Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.} @returns(200) {object: str, id: str, email_address: str(email), status: str, is_locked: bool, created_at: int(int64), updated_at: int(int64), invitation: map?} # A Waitlist Entry @errors {400: Request was not successful, 404: Resource not found, 409: Conflict, 422: Invalid request parameters} @endpoint POST /waitlist_entries/{waitlist_entry_id}/reject @desc Reject a waitlist entry @required {waitlist_entry_id: str # The ID of the waitlist entry to reject} @returns(200) {object: str, id: str, email_address: str(email), status: str, is_locked: bool, created_at: int(int64), updated_at: int(int64), invitation: map?} # A Waitlist Entry @errors {400: Request was not successful, 404: Resource not found, 409: Conflict, 422: Invalid request parameters} @endgroup @group billing @endpoint GET /billing/plans @desc List all billing plans @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., payer_type: str(user/org) # Filter plans by payer type} @returns(200) {data: [map], total_count: int(int64)} # A list of commerce plans. @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /billing/prices @desc List all billing prices @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., plan_id: str # Filter prices by plan ID} @returns(200) {data: [map], total_count: int(int64)} # A list of billing prices. @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint POST /billing/prices @desc Create a custom billing price @required {plan_id: str # The ID of the plan this price belongs to., amount: int(int64) # The monthly amount in cents. Must be at least $1 (100 cents) if not null.} @optional {currency: str=USD # The currency code (e.g., "USD"). Defaults to USD., annual_monthly_amount: int(int64) # The monthly amount in cents when billed annually. Must be at least $1 (100 cents) if not null., description: str # An optional description for this custom price.} @returns(200) {object: str, id: str, plan_id: str, instance_id: str, currency: str, currency_symbol: str, amount: int(int64), annual_monthly_amount: int(int64), fee: any?, annual_monthly_fee: any?, description: str?, is_default: bool, created_at: int(int64)} # A billing price. @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /billing/subscription_items @desc List all subscription items @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`., status: str(active/ended/past_due/upcoming/free_trial) # Filter subscription items by status, payer_type: str(user/org) # Filter subscription items by payer type, plan_id: str # Filter subscription items by plan ID, include_free: bool=false # Whether to include free plan subscription items, query: str # Search query to filter subscription items} @returns(200) {data: [map], total_count: int(int64)} # A list of commerce subscription items. @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters, 500: Request was not successful} @endpoint DELETE /billing/subscription_items/{subscription_item_id} @desc Cancel a subscription item @required {subscription_item_id: str # The ID of the subscription item to cancel} @optional {end_now: bool=false # Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)} @returns(200) {object: str, id: str, instance_id: str, status: str, credit: map{amount: any?, cycle_remaining_percent: num(float)}, credits: any?, plan_id: str?, price_id: str, plan: any?, plan_period: str, payment_method: map{object: str, id: str, payer_id: str, payment_type: str, is_default: bool, gateway: str, gateway_external_id: str, gateway_external_account_id: str?, last4: str?, status: str, wallet_type: str?, card_type: str?, expiry_year: int?, expiry_month: int?, created_at: int(int64), updated_at: int(int64), is_removable: bool}, lifetime_paid: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}, next_payment: any?, payer_id: str, payer: map{object: str, id: str, instance_id: str, user_id: str?, first_name: str?, last_name: str?, email: str?, organization_id: str?, organization_name: str?, image_url: str, credits_balance: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}, created_at: int(int64), updated_at: int(int64)}, is_free_trial: bool, period_start: int(int64), period_end: int(int64)?, proration_date: str(date), canceled_at: int(int64)?, past_due_at: int(int64)?, ended_at: int(int64)?, created_at: int(int64), updated_at: int(int64), seats: any?, totals: any?} # A commerce subscription item. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint POST /billing/subscription_items/{subscription_item_id}/extend_free_trial @desc Extend free trial for a subscription item @required {subscription_item_id: str # The ID of the subscription item to extend the free trial for, extend_to: str(date-time) # RFC3339 timestamp to extend the free trial to. Must be in the future and not more than 365 days from now.} @returns(200) {object: str, id: str, instance_id: str, status: str, credit: any?, plan_id: str, price_id: str, plan: any?, plan_period: str, payment_source_id: str, payment_source: any?, lifetime_paid: any?, amount: any?, next_invoice: any?, next_payment: any?, payer_id: str, payer: any?, is_free_trial: bool, period_start: int(int64)?, period_end: int(int64)?, proration_date: str, canceled_at: int(int64)?, past_due_at: int(int64)?, ended_at: int(int64)?, created_at: int(int64), updated_at: int(int64)} # A commerce subscription item. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint POST /billing/subscription_items/{subscription_item_id}/price_transition @desc Create a price transition for a subscription item @required {subscription_item_id: str # The ID of the subscription item to transition, from_price_id: str # The current price ID of the subscription item., to_price_id: str # The target price ID to transition to.} @returns(200) {object: str, subscription_item: map{object: str, id: str, instance_id: str, status: str, credit: any?, plan_id: str, price_id: str, plan: any?, plan_period: str, payment_source_id: str, payment_source: any?, lifetime_paid: any?, amount: any?, next_invoice: any?, next_payment: any?, payer_id: str, payer: any?, is_free_trial: bool, period_start: int(int64)?, period_end: int(int64)?, proration_date: str, canceled_at: int(int64)?, past_due_at: int(int64)?, ended_at: int(int64)?, created_at: int(int64), updated_at: int(int64)}, transition: map{previous_plan: map{object: str, id: str, name: str, fee: any?, annual_monthly_fee: any?, annual_fee: any?, amount: int(int64), amount_formatted: str, annual_monthly_amount: int(int64), annual_monthly_amount_formatted: str, annual_amount: int(int64), annual_amount_formatted: str, currency_symbol: str, currency: str, description: str, product_id: str, is_default: bool, is_recurring: bool, publicly_visible: bool, has_base_fee: bool, payer_type: [str], for_payer_type: str, slug: str, avatar_url: str, period: str, interval: int(int64), features: [map], free_trial_enabled: bool, free_trial_days: int(int64)?}, previous_price: map{object: str, id: str, plan_id: str, instance_id: str, currency: str, currency_symbol: str, amount: int(int64), annual_monthly_amount: int(int64), fee: any?, annual_monthly_fee: any?, description: str?, is_default: bool, created_at: int(int64)}, effective_at: int(int64), effective_mode: str, next_billing_date: int(int64)?, charged_immediately: bool, immediate_charge: any?, previous_subscription_item_status: str, previous_subscription_item_id: str}} # A commerce price transition. @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 409: Conflict, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /billing/statements @desc List all billing statements @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of billing statements. @errors {400: Request was not successful, 401: Authentication invalid, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /billing/statements/{statementID} @desc Retrieve a billing statement @required {statementID: str # The ID of the statement to retrieve.} @returns(200) {object: str, id: str, instance_id: str, timestamp: int(int64), payer: map{object: str, id: str, instance_id: str, user_id: str?, first_name: str?, last_name: str?, email: str?, organization_id: str?, organization_name: str?, image_url: str, credits_balance: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}, created_at: int(int64), updated_at: int(int64)}, status: str, totals: map{grand_total: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}, subtotal: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}, base_fee: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}, tax_total: map{amount: int(int64), amount_formatted: str, currency: str, currency_symbol: str}}, groups: [map]} # A billing statement. @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endpoint GET /billing/statements/{statementID}/payment_attempts @desc List payment attempts for a billing statement @required {statementID: str # The ID of the statement to retrieve payment attempts for.} @optional {paginated: bool # Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # A list of billing payment attempts. @errors {400: Request was not successful, 401: Authentication invalid, 404: Resource not found, 422: Invalid request parameters, 500: Request was not successful} @endgroup @group organization_permissions @endpoint GET /organization_permissions @desc Get a list of all organization permissions @optional {query: str # Returns organization permissions with ID, name, or key that match the given query. Uses exact match for permission ID and partial match for name and key., order_by: str # Allows to return organization permissions in a particular order. At the moment, you can order the returned permissions by their `created_at`, `name`, or `key`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want permissions to be returned in descending order according to their `created_at` property, you can use `-created_at`., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # Success @errors {401: Authentication invalid, 422: Invalid request parameters} @endpoint POST /organization_permissions @desc Create a new organization permission @required {name: str # The name of the permission., key: str # The key of the permission. Must have the format "org:feature:action" where feature and action are segments consisting of lowercase letters, digits, or underscores, for example "org:billing:manage" or "org:team:read". Cannot begin with "org:sys_" as that prefix is reserved for system permissions.} @optional {description: str # A description of the permission.} @returns(200) {object: str, id: str, name: str, key: str, description: str, type: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 402: Payment required, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /organization_permissions/{permission_id} @desc Get an organization permission @required {permission_id: str # The ID of the permission to retrieve} @returns(200) {object: str, id: str, name: str, key: str, description: str, type: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {401: Authentication invalid, 404: Resource not found} @endpoint PATCH /organization_permissions/{permission_id} @desc Update an organization permission @required {permission_id: str # The ID of the permission to update} @optional {name: str # The name of the permission., key: str # The key of the permission. Must have the format "org:feature:action" where feature and action are segments consisting of lowercase letters, digits, or underscores. Cannot begin with "org:sys_" as that prefix is reserved for system permissions., description: str # A description of the permission.} @returns(200) {object: str, id: str, name: str, key: str, description: str, type: str, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint DELETE /organization_permissions/{permission_id} @desc Delete an organization permission @required {permission_id: str # The ID of the permission to delete} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endgroup @group role_sets @endpoint GET /role_sets @desc Get a list of role sets @optional {query: str # Returns role sets with ID, name, or key that match the given query. Uses exact match for role set ID and partial match for name and key., order_by: str=-created_at # Allows to return role sets in a particular order. At the moment, you can order the returned role sets by their `created_at`, `name`, or `key`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want role sets 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`., limit: int=10 # Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`., offset: int=0 # Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.} @returns(200) {data: [map], total_count: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 422: Invalid request parameters} @endpoint POST /role_sets @desc Create a role set @required {name: str # The name of the new role set, default_role_key: str # The key of the role to use as the default role for new organization members. Must be one of the roles in the `roles` array., creator_role_key: str # The key of the role to assign to organization creators. Must be one of the roles in the `roles` array., roles: [str] # Array of role keys to include in the role set. Must contain at least one role and no more than 10 roles.} @optional {key: str # A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores. If not provided, a key will be generated from the name., description: str # Optional description for the role set, type: str(initial/custom) # The type of the role set. "initial" role sets are the default for new organizations. Only one role set can be "initial" per instance.} @returns(200) {object: str, id: str, name: str, key: str, description: str?, roles: [map], default_role: any?, creator_role: any?, type: str, role_set_migration: any?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 402: Payment required, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint GET /role_sets/{role_set_key_or_id} @desc Retrieve a role set @required {role_set_key_or_id: str # The key or ID of the role set} @returns(200) {object: str, id: str, name: str, key: str, description: str?, roles: [map], default_role: any?, creator_role: any?, type: str, role_set_migration: any?, created_at: int(int64), updated_at: int(int64)} # Success @errors {401: Authentication invalid, 403: Authorization invalid, 404: Resource not found} @endpoint PATCH /role_sets/{role_set_key_or_id} @desc Update a role set @required {role_set_key_or_id: str # The key or ID of the role set to update} @optional {name: str # The new name for the role set, key: str # A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores., description: str # Optional description for the role set, type: str # Set to "initial" to make this the default role set for new organizations. Only one role set can be "initial" per instance; setting this will change any existing initial role set to "custom"., default_role_key: str # The key of the role to use as the default role for new organization members. Must be an existing role in the role set., creator_role_key: str # The key of the role to assign to organization creators. Must be an existing role in the role set.} @returns(200) {object: str, id: str, name: str, key: str, description: str?, roles: [map], default_role: any?, creator_role: any?, type: str, role_set_migration: any?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /role_sets/{role_set_key_or_id}/replace @desc Replace a role set @required {role_set_key_or_id: str # The key or ID of the role set to replace, dest_role_set_key: str # The key of the destination role set} @optional {reassignment_mappings: any # Mappings from source role keys to destination role keys. Required if members have roles that need to be reassigned.} @returns(200) {object: str, id: str, slug: str, deleted: bool, external_id: str} # Deleted Object @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /role_sets/{role_set_key_or_id}/roles @desc Add roles to a role set @required {role_set_key_or_id: str # The key or ID of the role set, role_keys: [str] # Array of role keys to add to the role set. Must contain at least one role and no more than 10 roles.} @optional {default_role_key: str # Optionally update the default role to one of the newly added roles., creator_role_key: str # Optionally update the creator role to one of the newly added roles.} @returns(200) {object: str, id: str, name: str, key: str, description: str?, roles: [map], default_role: any?, creator_role: any?, type: str, role_set_migration: any?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endpoint POST /role_sets/{role_set_key_or_id}/roles/replace @desc Replace a role in a role set @required {role_set_key_or_id: str # The key or ID of the role set, role_key: str # The key of the role to remove from the role set, to_role_key: str # The key of the role to reassign members to} @returns(200) {object: str, id: str, name: str, key: str, description: str?, roles: [map], default_role: any?, creator_role: any?, type: str, role_set_migration: any?, created_at: int(int64), updated_at: int(int64)} # Success @errors {400: Request was not successful, 401: Authentication invalid, 403: Authorization invalid, 404: Resource not found, 422: Invalid request parameters} @endgroup @group api_keys @endpoint POST /api_keys @desc Create an API Key @required {name: str, subject: str} @optional {type: str=api_key, description: str, claims: any, scopes: [str]=, created_by: str, seconds_until_expiration: num} @returns(200) {object: str, id: str, type: str, subject: str, name: str, description: str?, claims: any?, scopes: [str], secret: str, revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, created_by: str?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 409: 409 Conflict} @endpoint GET /api_keys @desc Get API Keys @required {subject: str} @optional {type: str=api_key, include_invalid: str(true/false)=false, limit: num=10, offset: num=0, query: str} @returns(200) {data: [map], total_count: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint GET /api_keys/{apiKeyID} @desc Get an API Key by ID @required {apiKeyID: str} @returns(200) {object: str, id: str, type: str, subject: str, name: str, description: str?, claims: any?, scopes: [str], revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, created_by: str?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint PATCH /api_keys/{apiKeyID} @desc Update an API Key @required {apiKeyID: str} @optional {claims: any, scopes: [str], description: str, subject: str, seconds_until_expiration: num} @returns(200) {object: str, id: str, type: str, subject: str, name: str, description: str?, claims: any?, scopes: [str], revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, created_by: str?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint DELETE /api_keys/{apiKeyID} @desc Delete an API Key @required {apiKeyID: str} @returns(200) {id: str, object: str, deleted: bool} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint GET /api_keys/{apiKeyID}/secret @desc Get an API Key Secret @required {apiKeyID: str} @returns(200) {secret: str} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint POST /api_keys/{apiKeyID}/revoke @desc Revoke an API Key @required {apiKeyID: str} @optional {revocation_reason: str} @returns(200) {object: str, id: str, type: str, subject: str, name: str, description: str?, claims: any?, scopes: [str], revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, created_by: str?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint POST /api_keys/verify @desc Verify an API Key @required {secret: str} @returns(200) {object: str, id: str, type: str, subject: str, name: str, description: str?, claims: any?, scopes: [str], revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, created_by: str?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endgroup @group m2m_tokens @endpoint POST /m2m_tokens @desc Create a M2M Token @optional {token_format: str(opaque/jwt)=opaque, seconds_until_expiration: num, claims: any} @returns(201) {object: str, id: str, subject: str, claims: any?, scopes: [str], token: str, revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, last_used_at: num?, created_at: num, updated_at: num} # 201 Created @errors {400: 400 Bad Request, 409: 409 Conflict} @endpoint GET /m2m_tokens @desc Get M2M Tokens @required {subject: str} @optional {revoked: bool=false, expired: bool=false, limit: num=10, offset: num=0} @returns(200) {m2m_tokens: [map], total_count: num} # 200 OK @errors {400: 400 Bad Request, 403: 403 Forbidden, 404: 404 Not Found} @endpoint POST /m2m_tokens/{m2m_token_id}/revoke @desc Revoke a M2M Token @required {m2m_token_id: str} @optional {revocation_reason: str} @returns(200) {object: str, id: str, subject: str, claims: any?, scopes: [str], revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endpoint POST /m2m_tokens/verify @desc Verify a M2M Token @required {token: str} @returns(200) {object: str, id: str, subject: str, claims: any?, scopes: [str], revoked: bool, revocation_reason: str?, expired: bool, expiration: num?, last_used_at: num?, created_at: num, updated_at: num} # 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endgroup @group oauth_applications @endpoint POST /oauth_applications/access_tokens/verify @desc Verify an OAuth Access Token @optional {access_token: str # The access token to verify., secret: str # The access token to verify. This is deprecated, use `access_token` instead.} @returns(200) 200 OK @errors {400: 400 Bad Request, 404: 404 Not Found} @endgroup @end