Clerk

Clerk Backend API (2026-08-20)

The Clerk REST Backend API, meant to be accessed by backend servers. Versions When the API changes in a way that isn't compatible with older versions, a new…

Identity & security#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Clerk REST Backend API, meant to be accessed by backend servers.

Versions

When the API changes in a way that isn't compatible with older versions, a new version is released.
Each version is identified by its release date, e.g. 2025-04-10. For more information, please see Clerk API Versions.

Please see https://clerk.com/docs for more information.

Endpoints 264

Actor Tokens

  • POSTCreate actor token/actor_tokensCreate an actor token that can be used to impersonate the given user. The actor parameter needs to include at least a "sub" key whose value is the ID of the…
  • POSTRevoke actor token/actor_tokens/:actor_token_id/revokeRevokes a pending actor token.

Allow-list / Block-list

  • GETList all identifiers on the allow-list/allowlist_identifiers?paginated=true&limit=10&offset=0Get a list of all identifiers allowed to sign up to an instance
  • POSTAdd identifier to the allow-list/allowlist_identifiersCreate an identifier allowed to sign up to an instance
  • DELETEDelete identifier from allow-list/allowlist_identifiers/:identifier_idDelete an identifier from the instance allow-list
  • GETList all identifiers on the block-list/blocklist_identifiersGet a list of all identifiers which are not allowed to access an instance
  • POSTAdd identifier to the block-list/blocklist_identifiersCreate an identifier that is blocked from accessing an instance
  • DELETEDelete identifier from block-list/blocklist_identifiers/:identifier_idDelete an identifier from the instance block-list

Clients

  • GETList all clients/clients?paginated=true&limit=10&offset=0Deprecated. Returns a list of all clients. The clients are returned sorted by creation date, with the newest clients appearing first. Warning: the endpoint is…
  • POSTVerify a client/clients/verifyVerifies the client in the provided token
  • GETGet a client/clients/:client_idReturns the details of a client.

Billing

  • GETList all billing plans/billing/plans?paginated=true&limit=10&offset=0&payer_type=userReturns a list of all billing plans for the instance. The plans are returned sorted by creation date, with the newest plans appearing first. This includes…
  • GETList all billing prices/billing/prices?paginated=true&limit=10&offset=0&plan_id=stringReturns a list of all prices for the instance. The prices are returned sorted by amount ascending, then by creation date descending. This includes both…
  • POSTCreate a custom billing price/billing/pricesCreates a custom price for a billing plan. Custom prices allow you to offer different pricing to specific customers while maintaining the same plan structure.
  • GETList all subscription items/billing/subscription_items?paginated=true&limit=10&offset=0&status=active&payer_type=user&plan_id=string&include_free=false&query=stringReturns a list of all subscription items for the instance. The subscription items are returned sorted by creation date, with the newest appearing first. This…
  • DELETECancel a subscription item/billing/subscription_items/:subscription_item_id?end_now=falseCancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period.
  • POSTExtend free trial for a subscription item/billing/subscription_items/:subscription_item_id/extend_free_trialExtends the free trial period for a specific subscription item to the specified timestamp. The subscription item must be currently in a free trial period, and…
  • POSTCreate a price transition for a subscription item/billing/subscription_items/:subscription_item_id/price_transitionCreates a price transition for the specified subscription item. This may create an upcoming subscription item or activate immediately depending on plan and…
  • POSTApply a discount to a subscription item/billing/subscription_items/:subscription_item_id/discountsApplies an existing discount to a subscription item. Manual application is an override path: self-serve distribution rules are not enforced. At most one…
  • DELETERemove a discount from a subscription item/billing/subscription_items/:subscription_item_id/discounts/:discount_idRemoves the active discount from a subscription item. The discount_id must match the subscription item's currently active discount.
  • GETList all billing statements/billing/statements?paginated=true&limit=10&offset=0Returns a list of all billing statements for the instance. The statements are returned sorted by creation date, with the newest statements appearing first.…
  • GETRetrieve a billing statement/billing/statements/:statementIDRetrieves the details of a billing statement.
  • GETList payment attempts for a billing statement/billing/statements/:statementID/payment_attempts?paginated=true&limit=10&offset=0Returns a list of all payment attempts for a specific billing statement. The payment attempts are returned sorted by creation date, with the newest payment…

Domains

  • GETList all instance domains/domainsUse this endpoint to get a list of all domains for an instance. The response will contain the primary domain for the instance and any satellite domains. Each…
  • POSTAdd a domain/domainsAdd a new domain for your instance. Useful in the case of multi-domain instances, allows adding satellite domains to an instance. The new domain must have a…
  • DELETEDelete a domain/domains/:domain_idDeletes a domain for the instance. The instance's active domain cannot be deleted. Deleting a non-satellite domain returns 403 domain_managed_by_integration…
  • PATCHUpdate a domain/domains/:domain_idThe proxy_url can be updated only for production instances. Update one of the instance's domains. Both primary and satellite domains can be updated. If you…

Email Addresses

  • POSTCreate an email address/email_addressesCreate a new email address
  • GETRetrieve an email address/email_addresses/:email_address_idReturns the details of an email address.
  • DELETEDelete an email address/email_addresses/:email_address_idDelete the email address with the given ID
  • PATCHUpdate an email address/email_addresses/:email_address_idUpdates an email address.
  • POSTSend a verification code to an email address/email_addresses/:email_address_id/prepare_verificationSends a one-time code to the given email address so that a backend can verify the user controls it (for example, in a custom, backend-driven sign-in flow).…
  • POSTVerify a code sent to an email address/email_addresses/:email_address_id/attempt_verificationChecks a one-time code against the verification identified by verification_id, and returns the verification with its updated status (verified, unverified,…
  • PUTReplace a user's email address/users/:user_id/email_addressReplaces all of the user's email addresses with a single primary email address. By default the new email address is created verified, with the admin…

Email & SMS Templates

  • GETList all templates/templates/:template_type?paginated=true&limit=10&offset=0Deprecated. Returns a list of all templates. The templates are returned sorted by position.
  • GETRetrieve a template/templates/:template_type/:slugDeprecated. Returns the details of a template
  • PUTUpdate a template for a given type and slug/templates/:template_type/:slugDeprecated. Updates the existing template of the given type and slug
  • POSTRevert a template/templates/:template_type/:slug/revertDeprecated. Reverts an updated template to its default state
  • POSTPreview changes to a template/templates/:template_type/:slug/previewDeprecated. Returns a preview of a template for a given template_type, slug and body
  • POSTToggle the delivery by Clerk for a template of a given type and slug/templates/:template_type/:slug/toggle_deliveryDeprecated. Toggles the delivery by Clerk for a template of a given type and slug. If disabled, Clerk will not deliver the resulting email or SMS. The app…

Instance Settings

  • GETFetch the current instance/instanceFetches the current instance
  • PATCHUpdate instance settings/instanceUpdates the settings of an instance
  • PATCHUpdate instance restrictions/instance/restrictionsUpdates the restriction settings of an instance
  • GETGet instance protect settings/instance/protect
  • PATCHUpdate instance protect settings/instance/protect
  • GETGet instance communication settings/instance/communicationRetrieves the per-instance SMS communication settings, including the SMS country blocklist.
  • PATCHUpdate instance communication settings/instance/communicationReplaces the SMS country blocklist for this instance. Pass the full set of ISO 3166-1 alpha-2 country codes that should be blocked; codes that aren't…
  • GETGet OAuth application settings/instance/oauth_application_settingsRetrieves the settings for OAuth applications for the instance (dynamic client registration, JWT access tokens, etc.).
  • PATCHUpdate OAuth application settings/instance/oauth_application_settingsUpdates the OAuth application settings for the instance.
  • GETGet instance organization settings/instance/organization_settingsRetrieves the organization settings of the instance
  • PATCHUpdate instance organization settings/instance/organization_settingsUpdates the organization settings of the instance

Invitations

  • GETList all invitations/invitations?status=pending&query=string&email_address=string&order_by=-created_at&paginated=true&limit=10&offset=0Returns non-revoked invitations for your application, sorted by creation date. Without limit, offset or paginated=true, returns at most 500 invitations.
  • POSTCreate an invitation/invitationsCreates a new invitation for the given email address and sends the invitation email. Keep in mind that you cannot create an invitation if there is already one…
  • POSTCreate multiple invitations/invitations/bulkUse this API operation to create multiple invitations for the provided email addresses. You can choose to send the invitations as emails by setting the notify…
  • DELETEDelete an invitation/invitations/:invitation_idPermanently deletes the given invitation and the copies of the invitation email Clerk stored for its recipient. Unlike revoking, deleting removes the…
  • POSTRevokes an invitation/invitations/:invitation_id/revokeRevokes the given invitation. Revoking an invitation will prevent the user from using the invitation link that was sent to them. However, it doesn't prevent…

JWKS

  • GETRetrieve the JSON Web Key Set of the instance/jwksRetrieve the JSON Web Key Set of the instance

JWT Templates

  • GETList all templates/jwt_templates?paginated=true&limit=10&offset=0
  • POSTCreate a JWT template/jwt_templatesCreate a new JWT template
  • GETRetrieve a template/jwt_templates/:template_idRetrieve the details of a given JWT template
  • DELETEDelete a Template/jwt_templates/:template_id
  • PATCHUpdate a JWT template/jwt_templates/:template_idUpdates an existing JWT template

OAuth Applications

  • GETGet a list of OAuth applications for an instance/oauth_applications?limit=10&offset=0&order_by=+created_at&name_query=stringThis request returns the list of OAuth applications for an instance. Results can be paginated using the optional limit and offset query parameters. The OAuth…
  • POSTCreate an OAuth application/oauth_applicationsCreates a new OAuth application with the given name and callback URL for an instance. The callback URL must be a valid URL. All URL schemes are allowed such…
  • GETRetrieve an OAuth application by ID/oauth_applications/:oauth_application_idFetches the OAuth application whose ID matches the provided id in the path.
  • DELETEDelete an OAuth application/oauth_applications/:oauth_application_idDeletes the given OAuth application. This is not reversible.
  • PATCHUpdate an OAuth application/oauth_applications/:oauth_application_idUpdates an existing OAuth application
  • PUTUpload a logo for the OAuth application/oauth_applications/:oauth_application_id/logoSet or replace an OAuth application's logo by uploading an image file. This endpoint uses the multipart/form-data request content type and accepts a file of…
  • POSTRotate the client secret of the given OAuth application/oauth_applications/:oauth_application_id/rotate_secretRotates the OAuth application's client secret. When the client secret is rotated, make sure to update it in authorized OAuth clients.
  • POSTRevoke an OAuth application token/oauth_applications/:oauth_application_id/revoke_tokenRevoke both OAuth access token and refresh token for the associated grant for the given OAuth application. The request may specify either token. JWT access…

OAuth Access Tokens

  • POSTVerify an OAuth Access Token/oauth_applications/access_tokens/verify

Organizations

  • GETGet a list of organizations for an instance/organizations?include_members_count=true&include_missing_member_with_elevated_permissions=true&query=string&user_id=string&organization_id=string&order_by=-created_at&limit=10&offset=0This request returns the list of organizations for an instance. Results can be paginated using the optional limit and offset query parameters. The…
  • POSTCreate an organization/organizationsCreates a new organization with the given name for an instance. You can specify an optional slug for the new organization. If provided, the organization slug…
  • GETRetrieve an organization by ID or slug/organizations/:organization_id?include_members_count=true&include_missing_member_with_elevated_permissions=trueFetches the organization whose ID or slug matches the provided id_or_slug URL query parameter.
  • DELETEDelete an organization/organizations/:organization_idDeletes the given organization. Please note that deleting an organization will also delete all memberships and invitations. This is not reversible. After the…
  • PATCHUpdate an organization/organizations/:organization_idUpdates an existing organization. As of API version 2026-05-12, this endpoint no longer accepts public_metadata or private_metadata. Use PATCH…
  • PUTReplace metadata for an organization/organizations/:organization_id/metadataReplace an organization's metadata attributes with the provided values. Unlike PATCH /v1/organizations/{organization_id}/metadata (merge semantics), this…
  • PATCHMerge and update metadata for an organization/organizations/:organization_id/metadataUpdate organization metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. Deep…
  • PUTUpload a logo for the organization/organizations/:organization_id/logoSet or replace an organization's logo, by uploading an image file. This endpoint uses the multipart/form-data request content type and accepts a file of image…
  • DELETEDelete the organization's logo./organizations/:organization_id/logoDelete the organization's logo.
  • GETRetrieve an organization's billing subscription/organizations/:organization_id/billing/subscriptionRetrieves the billing subscription for the specified organization. This includes subscription details, active plans, billing information, and payment status.…
  • GETRetrieve an organization's credit balance/organizations/:organization_id/billing/creditsRetrieves the current credit balance for the specified organization. Credits can be applied during checkout to reduce the charge or automatically applied to…
  • POSTAdjust an organization's credit balance/organizations/:organization_id/billing/creditsIncreases or decreases the credit balance for the specified organization. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures…

Organization Invitations

  • GETGet a list of organization invitations for the current instance/organization_invitations?order_by=-created_at&status=pending&query=string&limit=10&offset=0This request returns the list of organization invitations for the instance. Results can be paginated using the optional limit and offset query parameters. You…
  • GETGet a list of organization invitations/organizations/:organization_id/invitations?status=pending&email_address=string&order_by=-created_at&limit=10&offset=0This request returns the list of organization invitations. Results can be paginated using the optional limit and offset query parameters. You can filter them…
  • POSTCreate and send an organization invitation/organizations/:organization_id/invitationsCreates a new organization invitation and sends an email to the provided email_address with a link to accept the invitation and join the organization. You can…
  • POSTBulk create and send organization invitations/organizations/:organization_id/invitations/bulkCreates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the…
  • GETGet a list of pending organization invitations/organizations/:organization_id/invitations/pending?limit=10&offset=0Deprecated. This request returns the list of organization invitations with "pending" status. These are the organization invitations that can still be used to…
  • GETRetrieve an organization invitation by ID/organizations/:organization_id/invitations/:invitation_idUse this request to get an existing organization invitation by ID.
  • POSTRevoke a pending organization invitation/organizations/:organization_id/invitations/:invitation_id/revokeUse this request to revoke a previously issued organization invitation. Revoking an organization invitation makes it invalid; the invited user will no longer…

Organization Memberships

  • GETGet a list of all members of an organization/organizations/:organization_id/memberships?order_by=string&user_id=string&email_address=string&phone_number=string&username=string&web3_wallet=string&role=string&query=string&email_address_query=string&phone_number_query=string&username_query=string&name_query=string&last_active_at_before=1700690400000&last_active_at_after=1700690400000&created_at_before=1730160000000&created_at_after=1730160000000&limit=10&offset=0Retrieves all user memberships for the given organization
  • POSTCreate a new organization membership/organizations/:organization_id/membershipsAdds a user as a member to the given organization. Only users in the same instance as the organization can be added as members. This organization will be the…
  • DELETERemove a member from an organization/organizations/:organization_id/memberships/:user_idRemoves the given membership from the organization
  • PATCHUpdate an organization membership/organizations/:organization_id/memberships/:user_idUpdates the properties of an existing organization membership
  • PATCHMerge and update organization membership metadata/organizations/:organization_id/memberships/:user_id/metadataUpdate an organization membership's metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep…
  • GETGet a list of all organization memberships within an instance./organization_memberships?order_by=string&limit=10&offset=0Retrieves all organization user memberships for the given instance.

Organization Permissions

  • GETGet a list of all organization permissions/organization_permissions?query=string&order_by=string&limit=10&offset=0Retrieves all organization permissions for the given instance.
  • POSTCreate a new organization permission/organization_permissionsCreates a new organization permission for the given instance.
  • GETGet an organization permission/organization_permissions/:permission_idRetrieves the details of an organization permission.
  • DELETEDelete an organization permission/organization_permissions/:permission_idDeletes an organization permission. System permissions cannot be deleted.
  • PATCHUpdate an organization permission/organization_permissions/:permission_idUpdates the properties of an existing organization permission. System permissions cannot be updated.

Organization Roles

  • GETGet a list of organization roles/organization_roles?query=string&order_by=-created_at&limit=10&offset=0This request returns the list of organization roles for the instance. Results can be paginated using the optional limit and offset query parameters. The…
  • POSTCreate an organization role/organization_rolesCreates a new organization role with the given name and permissions for an instance. The key must be unique for the instance and start with the 'org:' prefix,…
  • GETRetrieve an organization role/organization_roles/:organization_role_idUse this request to retrieve an existing organization role by its ID.
  • DELETEDelete an organization role/organization_roles/:organization_role_idDeletes the organization role. The role cannot be deleted if it is currently used as the default creator role, domain default role, assigned to any members,…
  • PATCHUpdate an organization role/organization_roles/:organization_role_idUpdates an existing organization role. You can update the name, key, description, and permissions of the role. All parameters are optional - you can update…
  • POSTAssign a permission to an organization role/organization_roles/:organization_role_id/permissions/:permission_idAssigns a permission to an organization role
  • DELETERemove a permission from an organization role/organization_roles/:organization_role_id/permissions/:permission_idRemoves a permission from an organization role

Role Sets

  • GETGet a list of role sets/role_sets?query=string&order_by=-created_at&limit=10&offset=0Returns a list of role sets for the instance. Results can be paginated using the optional limit and offset query parameters. The role sets are ordered by…
  • POSTCreate a role set/role_setsCreates a new role set with the given name and roles. The key must be unique for the instance and start with the 'role_set:' prefix, followed by lowercase…
  • GETRetrieve a role set/role_sets/:role_set_key_or_idRetrieves an existing role set by its key or ID.
  • PATCHUpdate a role set/role_sets/:role_set_key_or_idUpdates an existing role set. You can update the name, key, description, type, default role, or creator role. All parameters are optional - you can update…
  • POSTReplace a role set/role_sets/:role_set_key_or_id/replaceReplaces a role set with another role set. This is functionally equivalent to deleting the role set but allows for atomic replacement with migration support.…
  • POSTAdd roles to a role set/role_sets/:role_set_key_or_id/rolesAdds one or more roles to an existing role set. You can optionally update the default role or creator role when adding new roles.
  • POSTReplace a role in a role set/role_sets/:role_set_key_or_id/roles/replaceReplaces a role in a role set with another role. This atomically removes the source role and reassigns any members to the destination role.

Phone Numbers

  • POSTCreate a phone number/phone_numbersCreate a new phone number
  • GETRetrieve a phone number/phone_numbers/:phone_number_idReturns the details of a phone number
  • DELETEDelete a phone number/phone_numbers/:phone_number_idDelete the phone number with the given ID
  • PATCHUpdate a phone number/phone_numbers/:phone_number_idUpdates a phone number
  • POSTSend a verification code to a phone number/phone_numbers/:phone_number_id/prepare_verificationSends a one-time code to the given phone number so that a backend can verify the user controls it (for example, in a custom, backend-driven sign-in flow). The…
  • POSTVerify a code sent to a phone number/phone_numbers/:phone_number_id/attempt_verificationChecks a one-time code against the verification identified by verification_id, and returns the verification with its updated status (verified, unverified,…
  • PUTReplace a user's phone number/users/:user_id/phone_numberReplaces all of the user's phone numbers with a single primary phone number. By default the new phone number is created verified, with the admin verification…

Redirect URLs

  • GETList all redirect URLs/redirect_urls?paginated=true&limit=10&offset=0Lists all whitelisted redirect_urls for the instance
  • POSTCreate a redirect URL/redirect_urlsCreate a redirect URL
  • GETRetrieve a redirect URL/redirect_urls/:idRetrieve the details of the redirect URL with the given ID
  • DELETEDelete a redirect URL/redirect_urls/:idRemove the selected redirect URL from the whitelist of the instance

SAML Connections

  • GETGet a list of SAML Connections for an instance/saml_connections?limit=10&offset=0&query=string&order_by=string&organization_id=stringDeprecated. Returns the list of SAML Connections for an instance. Results can be paginated using the optional limit and offset query parameters. The SAML…
  • POSTCreate a SAML Connection/saml_connectionsDeprecated. Create a new SAML Connection. Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.
  • GETRetrieve a SAML Connection by ID/saml_connections/:saml_connection_idDeprecated. Fetches the SAML Connection whose ID matches the provided saml_connection_id in the path. Deprecated: Use the Enterprise Connections API instead.…
  • DELETEDelete a SAML Connection/saml_connections/:saml_connection_idDeprecated. Deletes the SAML Connection whose ID matches the provided id in the path. Deprecated: Use the Enterprise Connections API instead. This endpoint…
  • PATCHUpdate a SAML Connection/saml_connections/:saml_connection_idDeprecated. Updates the SAML Connection whose ID matches the provided id in the path. Deprecated: Use the Enterprise Connections API instead. This endpoint…

Enterprise Connections

  • GETList enterprise connections/enterprise_connections?limit=10&offset=0&organization_id=string&active=trueReturns the list of enterprise connections for the instance. Results can be paginated using the optional limit and offset query parameters.
  • POSTCreate an enterprise connection/enterprise_connectionsCreate a new enterprise connection.
  • GETRetrieve an enterprise connection/enterprise_connections/:enterprise_connection_idFetches the enterprise connection whose ID matches the provided enterprise_connection_id in the path.
  • DELETEDelete an enterprise connection/enterprise_connections/:enterprise_connection_idDeletes the enterprise connection whose ID matches the provided enterprise_connection_id in the path.
  • PATCHUpdate an enterprise connection/enterprise_connections/:enterprise_connection_idUpdates the enterprise connection whose ID matches the provided enterprise_connection_id in the path. When enabling the connection (setting active to true),…
  • GETList enterprise connection test runs/enterprise_connections/:enterprise_connection_id/test_runs?status=pending&limit=10&offset=0Returns a paginated list of SAML or OIDC debug test runs for an enterprise connection.
  • POSTCreate an enterprise connection test run/enterprise_connections/:enterprise_connection_id/test_runsReturns a short-lived URL that starts the IdP test flow for this connection.

SSO Bypass

  • GETList the SSO bypass allowlist/sso_bypass_allowlist_users?enterprise_connection_id=stringReturns the users who may verify an email code instead of reaching their identity provider when enterprise SSO is unreachable.
  • POSTAdd a user to the SSO bypass allowlist/sso_bypass_allowlist_usersPuts a user on the allowlist. The request is rejected unless the user holds a verified email address on a domain one of the instance's enterprise connections…
  • DELETERemove a user from the SSO bypass allowlist/sso_bypass_allowlist_users/:userIDRemoves the user from the allowlist, across every enterprise connection that serves them.

Sessions

  • GETList all sessions/sessions?client_id=string&user_id=string&status=abandoned&paginated=true&limit=10&offset=0Returns a list of sessions matching the provided criteria. The sessions are returned sorted by creation date, with the newest sessions appearing first. Note:…
  • POSTCreate a new active session/sessionsCreate a new active session for the provided user ID. This operation is intended only for use in testing, and is not available for production instances. If…
  • GETRetrieve a session/sessions/:session_idRetrieve the details of a session
  • PATCHUpdate a session/sessions/:session_idChanges when a session expires. Use this to give one session a longer or shorter lifetime than the one configured for your instance, for example to keep a…
  • POSTRefresh a session/sessions/:session_id/refreshRefreshes a session by creating a new session token. A 401 is returned when there are validation errors, which signals the SDKs to fall back to the handshake…
  • GETRetrieve a reverification/sessions/:session_id/reverifications/:reverification_idRetrieve a reverification scoped to a session. A resource server can use this to validate a reverification id it received from its client: confirm it is real,…
  • POSTRevoke a session/sessions/:session_id/revokeSets the status of a session as "revoked", which is an unauthenticated state. In multi-session mode, a revoked session will still be returned along with its…
  • POSTCreate a session token/sessions/:session_id/tokensCreates a session JSON Web Token (JWT) based on a session.
  • POSTCreate a session token from a JWT template/sessions/:session_id/tokens/:template_nameCreates a JSON Web Token (JWT) based on a session and a JWT Template name defined for your instance

Machines

  • GETGet a list of machines for an instance/machines?limit=10&offset=0&query=string&order_by=-created_atThis request returns the list of machines for an instance. The machines are ordered by descending creation date (i.e. most recent machines will be returned…
  • POSTCreate a machine/machinesCreates a new machine.
  • GETRetrieve a machine/machines/:machine_idReturns the details of a machine.
  • DELETEDelete a machine/machines/:machine_idDeletes a machine.
  • PATCHUpdate a machine/machines/:machine_idUpdates an existing machine. Only the provided fields will be updated.
  • GETRetrieve a machine secret key/machines/:machine_id/secret_keyReturns the secret key for a machine.
  • POSTRotate a machine's secret key/machines/:machine_id/secret_key/rotateRotates the machine's secret key. When the secret key is rotated, make sure to update it in your machine/application. The previous secret key will remain…
  • POSTCreate a machine scope/machines/:machine_id/scopesCreates a new machine scope, allowing the specified machine to access another machine. Maximum of 150 scopes per machine.
  • DELETEDelete a machine scope/machines/:machine_id/scopes/:other_machine_idDeletes a machine scope, removing access from one machine to another.

M2M Tokens

  • GETGet M2M Tokens/m2m_tokens?subject=string&revoked=false&expired=false&limit=10&offset=0Fetches M2M tokens for a specific machine. Only tokens created with the opaque token format are returned by this endpoint. JWT-format M2M tokens are stateless…
  • POSTCreate a M2M Token/m2m_tokensCreates a new M2M Token. Must be authenticated via a Machine Secret Key.
  • POSTRevoke a M2M Token/m2m_tokens/:m2m_token_id/revokeRevokes a M2M Token. This endpoint only revokes stored opaque-format M2M tokens. JWT-format M2M tokens are stateless and cannot be revoked. This endpoint can…
  • POSTVerify a M2M Token/m2m_tokens/verifyVerifies a M2M Token. This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key. When verifying a M2M Token with a Machine…

API Keys

  • GETGet API Keys/api_keys?type=api_key&subject=string&include_invalid=false&limit=10&offset=0&query=string
  • POSTCreate an API Key/api_keys
  • GETGet an API Key by ID/api_keys/:apiKeyID
  • DELETEDelete an API Key/api_keys/:apiKeyID
  • PATCHUpdate an API Key/api_keys/:apiKeyID
  • GETGet an API Key Secret/api_keys/:apiKeyID/secret
  • POSTRevoke an API Key/api_keys/:apiKeyID/revoke
  • POSTVerify an API Key/api_keys/verify

Sign-in Tokens

  • POSTCreate sign-in token/sign_in_tokensCreates a new sign-in token and associates it with the given user. By default, sign-in tokens expire in 30 days. You can optionally supply a different…
  • POSTRevoke the given sign-in token/sign_in_tokens/:sign_in_token_id/revokeRevokes a pending sign-in token

Sign Ups

  • GETRetrieve a sign-up by ID/sign_ups/:idRetrieve the details of the sign-up with the given ID
  • PATCHUpdate a sign-up/sign_ups/:idUpdate the sign-up with the given ID

Testing Tokens

  • POSTRetrieve a new testing token/testing_tokensRetrieve a new testing token.

Agent Tasks

  • POSTCreate agent task/agents/tasksCreate an agent task on behalf of a user. The response contains a URL that, when visited, creates a session for the user. The agent_id is stable per…
  • POSTRevoke agent task/agents/tasks/:agent_task_id/revokeRevokes a pending agent task.

Users

  • GETList all users/users?email_address=string&phone_number=string&external_id=string&username=string&web3_wallet=string&user_id=string&organization_id=string&query=string&email_address_query=string&phone_number_query=string&username_query=string&name_query=string&banned=true&last_active_at_before=1700690400000&last_active_at_after=1700690400000&last_active_at_since=1700690400000&created_at_before=1730160000000&created_at_after=1730160000000&last_sign_in_at_before=1700690400000&last_sign_in_at_after=1700690400000&provider=string&provider_user_id=string&limit=10&offset=0&starting_after=string&order_by=-created_atReturns a list of all users. The users are returned sorted by creation date, with the newest users appearing first. To walk more than a few pages, paginate…
  • POSTCreate a new user/usersCreates a new user. Your user management settings determine how you should setup your user model. By default, any email address and phone number created using…
  • GETCount users/users/count?email_address=string&phone_number=string&external_id=string&username=string&web3_wallet=string&user_id=string&organization_id=string&query=string&email_address_query=string&phone_number_query=string&username_query=string&name_query=string&banned=true&last_active_at_before=1700690400000&last_active_at_after=1700690400000&last_active_at_since=1700690400000&created_at_before=1730160000000&created_at_after=1730160000000&last_sign_in_at_before=1700690400000&last_sign_in_at_after=1700690400000&provider=string&provider_user_id=stringReturns a total count of all users that match the given filtering criteria.
  • GETRetrieve a user/users/:user_idRetrieve the details of a user
  • DELETEDelete a user/users/:user_idDelete the specified user
  • PATCHUpdate a user/users/:user_idUpdate a user's attributes. You can set the user's primary contact identifiers (email address and phone numbers) by updating the primary_email_address_id and…
  • POSTBan a user/users/:user_id/banMarks the given user as banned, which means that all their sessions and OAuth grants are revoked and they are not allowed to sign in again. Revoked OAuth…
  • POSTUnban a user/users/:user_id/unbanRemoves the ban mark from the given user.
  • POSTBan multiple users/users/banMarks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again.
  • POSTUnban multiple users/users/unbanRemoves the ban mark from multiple users.
  • POSTLock a user/users/:user_id/lockMarks the given user as locked, which means they are not allowed to sign in again until the lock expires. Lock duration can be configured in the instance's…
  • POSTUnlock a user/users/:user_id/unlockRemoves the lock from the given user.
  • POSTMerge another user into this user/users/:user_id/mergeMoves the identifications, connected accounts, passkeys, TOTP, backup codes, organization memberships, membership requests, suggestions and metadata of the…
  • POSTSet user profile image/users/:user_id/profile_imageUpdate a user's profile image
  • DELETEDelete user profile image/users/:user_id/profile_imageDelete a user's profile image
  • PUTReplace a user's metadata/users/:user_id/metadataReplace a user's metadata attributes with the provided values. Unlike PATCH /v1/users/{user_id}/metadata (merge semantics), this endpoint replaces the…
  • PATCHMerge and update a user's metadata/users/:user_id/metadataUpdate a user's metadata attributes by merging existing values with the provided parameters. This endpoint behaves differently than the *Update a user*…
  • GETRetrieve a user's billing subscription/users/:user_id/billing/subscriptionRetrieves the billing subscription for the specified user. This includes subscription details, active plans, billing information, and payment status. The…
  • GETRetrieve a user's credit balance/users/:user_id/billing/creditsRetrieves the current credit balance for the specified user. Credits can be applied during checkout to reduce the charge or automatically applied to upcoming…
  • POSTAdjust a user's credit balance/users/:user_id/billing/creditsIncreases or decreases the credit balance for the specified user. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures that…
  • GETRetrieve the OAuth access token of a user/users/:user_id/oauth_access_tokens/:provider?paginated=true&limit=10&offset=0Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider. For OAuth 2.0, if the access token…
  • GETRetrieve all memberships for a user/users/:user_id/organization_memberships?limit=10&offset=0Retrieve a paginated list of the user's organization memberships
  • GETRetrieve all invitations for a user/users/:user_id/organization_invitations?limit=10&offset=0&status=pendingRetrieve a paginated list of the user's organization invitations
  • POSTRemove a user's password/users/:user_id/remove_passwordRemoves the password credential from the given user. This is a privileged operation and does not require the user's current password. Password removal is…
  • POSTVerify the password of a user/users/:user_id/verify_passwordCheck that the user's password matches the supplied input. Useful for custom auth flows and re-verification.
  • POSTVerify a TOTP or backup code for a user/users/:user_id/verify_totpVerify that the provided TOTP or backup code is valid for the user. Verifying a backup code will result it in being consumed (i.e. it will become invalid).…
  • DELETEDisable a user's MFA methods/users/:user_id/mfaDisable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP on their authenticator app) at once.
  • DELETEDisable all user's Backup codes/users/:user_id/backup_codeDisable all of a user's backup codes.
  • DELETEDelete a user passkey/users/:user_id/passkeys/:passkey_identification_idDelete the passkey identification for a given user. The user is notified through email or SMS unless the passkey registration was never completed.
  • GETList a user's trusted devices/users/:user_id/trusted_devicesDeprecated. Returns the active trusted devices enrolled by the user.
  • DELETERevoke a user's trusted device/users/:user_id/trusted_devices/:trusted_device_idDeprecated. Revokes an active trusted device enrolled by the user.
  • GETList a user's biometric credentials/users/:user_id/biometric_credentialsReturns the active biometric credentials enrolled by the user.
  • DELETERevoke a user's biometric credential/users/:user_id/biometric_credentials/:biometric_credential_idRevokes an active biometric credential enrolled by the user.
  • DELETEDelete a user web3 wallet/users/:user_id/web3_wallets/:web3_wallet_identification_idDelete the web3 wallet identification for a given user.
  • DELETEDelete all the user's TOTPs/users/:user_id/totpDeletes all of the user's TOTPs.
  • DELETEDelete External Account/users/:user_id/external_accounts/:external_account_idDelete an external account by ID.
  • POSTSet a user's password as compromised/users/:user_id/password/set_compromisedSets the given user's password as compromised. The user will be prompted to reset their password on their next sign-in.
  • POSTUnset a user's password as compromised/users/:user_id/password/unset_compromisedSets the given user's password as no longer compromised. The user will no longer be prompted to reset their password on their next sign-in. If the user is in…

Webhooks

  • POSTCreate a Svix app/webhooks/svixCreate a Svix app and associate it with the current instance
  • DELETEDelete a Svix app/webhooks/svixDelete a Svix app and disassociate it from the current instance
  • POSTCreate a Svix Dashboard URL/webhooks/svix_urlGenerate a new URL for accessing the Svix's management dashboard for that particular instance

Miscellaneous

  • GETReturns the markup for the interstitial page/public/interstitial?frontendApi=string&frontend_api=string&publishable_key=string&proxy_url=string&domain=string&sign_in_url=string&use_domain_for_script=trueThe Clerk interstitial endpoint serves an html page that loads clerk.js in order to check the user's authentication state. It is used by Clerk SDKs when the…

Beta Features

  • PATCHUpdate instance settings/beta_features/instance_settingsUpdates the settings of an instance
  • PUTUpdate production instance domain/beta_features/domainDeprecated. Change the domain of a production instance. Changing the domain requires updating the DNS records accordingly, deploying new SSL certificates,…
  • POSTUpdate production instance domain/instance/change_domainChange the domain of a production instance. Changing the domain requires updating the DNS records accordingly, deploying new SSL certificates, updating your…

Waitlist Entries

  • GETList all waitlist entries/waitlist_entries?limit=10&offset=0&query=string&status=pending&order_by=-created_atRetrieve a list of waitlist entries for the instance. Entries are ordered by creation date in descending order by default. Supports filtering by email address…
  • POSTCreate a waitlist entry/waitlist_entriesCreates a new waitlist entry for the given email address. If the email address is already on the waitlist, no new entry will be created and the existing…
  • POSTCreate multiple waitlist entries/waitlist_entries/bulkCreates multiple waitlist entries for the provided email addresses. You can choose whether to send confirmation emails by setting the notify parameter to true…
  • DELETEDelete a pending waitlist entry/waitlist_entries/:waitlist_entry_idDelete a pending waitlist entry.
  • POSTInvite a waitlist entry/waitlist_entries/:waitlist_entry_id/inviteSend an invite to the email address in a waitlist entry.
  • POSTReject a waitlist entry/waitlist_entries/:waitlist_entry_id/rejectReject a waitlist entry.

Proxy Checks

  • POSTVerify the proxy configuration for your domain/proxy_checksThis endpoint can be used to validate that a proxy-enabled domain is operational. It tries to verify that the proxy URL provided in the parameters maps to a…

Organization Domains

  • GETGet a list of all domains of an organization./organizations/:organization_id/domains?verified=string&enrollment_mode=string&limit=10&offset=0Get a list of all domains of an organization.
  • POSTCreate a new organization domain./organizations/:organization_id/domainsCreates a new organization domain. By default the domain is verified, but can be optionally set to unverified.
  • DELETERemove a domain from an organization./organizations/:organization_id/domains/:domain_idRemoves the given domain from the organization.
  • PATCHUpdate an organization domain./organizations/:organization_id/domains/:domain_idUpdates the properties of an existing organization domain.
  • POSTMark an organization domain's ownership as verified/organizations/:organization_id/domains/:domain_id/verify_ownershipFlips the organization domain's ownership state to verified via the manual override path, bypassing the self-serve TXT DNS challenge. The domain row records…
  • GETList all organization domains/organization_domains?organization_id=string&verified=true&enrollment_mode=manual_invitation&query=string&domains=string&order_by=-created_at&offset=0&limit=10Retrieves a list of all organization domains within the current instance. This endpoint can be used to list all domains across all organizations or filter…

Logs

  • GETList all logs/logs?limit=10&starting_after=string&ending_before=string&subject=string&actor=string&user_id=user_2abcDEF&identifier=ana@example.com&trace_id=1234567890abcdef1234567890abcdef&type=string&client_id=string&session_id=sess_2abcDEF&impersonator_user_id=string&ip_address=string&payload_filter={"additionalProp1":"string"}&payload_fields=string&filter_match=all&event_time_after=1705315800000&event_time_before=1705319400000&end_user_facing_only=true&view=grouped&group_type=string&status=stringReturns a list of logs for the authenticated instance. Use it to find specific events, such as one user's failed sign-ins or every event in a trace. Narrow…
  • GETRetrieve the payload schema of a log event type/logs/schemas?type=sign_in.*Returns the payload schema of a log event type: which fields its payload carries, addressed by the dot-paths that the payload_filter and payload_fields…
  • GETList an event group's logs/logs/groups/:group_id/events?started_at=0&limit=10&starting_after=stringReturns the log entries of one event group past the ones a grouped page of GET /logs includes, oldest first, for loading more of a group. Accepts the same…
  • GETRetrieve a single log/logs/:event_time_and_idReturns a single log entry by its composite key ({event_time_ms}:{event_id}). Unlike the list endpoint, this returns the full payload for the event.

SCIM Directories

  • GETList all directories/scim_directories?limit=10&offset=0Returns a list of all directories for the instance.
  • POSTCreate a directory/scim_directoriesCreate a new directory for the instance.
  • GETRetrieve a directory/scim_directories/:scim_directory_idReturns the details of a directory.
  • DELETEDelete a directory/scim_directories/:scim_directory_idDeletes a directory and stops provisioning for it. SCIM requests authenticated with the directory's API key are rejected afterwards.
  • PATCHUpdate a directory/scim_directories/:scim_directory_idUpdates a directory.
  • POSTRotate a directory's API key/scim_directories/:scim_directory_id/rotate_api_keyGenerates a new API key for the directory and returns it in the api_key field. This is the only way to obtain the key after creation, so make sure to update…
  • GETList SCIM group role mappings/scim_directories/:scim_directory_id/group_role_mappingsReturns the list of SCIM group to organization role mappings for a directory, ordered by precedence.
  • PUTReplace SCIM group role mappings/scim_directories/:scim_directory_id/group_role_mappingsReplaces the entire set of SCIM group role mappings for a directory. The position of each item in the mappings array determines its precedence (the first item…
  • POSTCreate a SCIM group role mapping/scim_directories/:scim_directory_id/group_role_mappingsCreates a new SCIM group to organization role mapping for a directory. Mappings can be created while group role mapping is disabled on the directory, but they…
  • DELETEDelete a SCIM group role mapping/scim_directories/:scim_directory_id/group_role_mappings/:mapping_idDeletes a single SCIM group role mapping. Mappings can be deleted while group role mapping is disabled on the directory, but the change only takes effect once…

Directories

  • GETList all directories/directories?limit=10&offset=0Returns a list of all directories for the instance.
  • POSTCreate a directory/directoriesCreate a new directory for the instance.
  • GETRetrieve a directory/directories/:directory_idReturns the details of a directory.
  • DELETEDelete a directory/directories/:directory_idDeletes a directory and stops provisioning for it. Provisioning requests authenticated with the directory's API key are rejected afterwards.
  • PATCHUpdate a directory/directories/:directory_idUpdates a directory.
  • POSTRotate a directory's API key/directories/:directory_id/rotate_api_keyGenerates a new API key for the directory and returns it in the api_key field. This is the only way to obtain the key after creation, so make sure to update…
  • GETRetrieve a directory group/directories/:directory_id/groups/:group_idReturns one group of the directory, as reported by the identity provider. Responds with 404 once the identity provider has deleted the group.
  • GETList directory group members/directories/:directory_id/groups/:group_id/members?limit=10&starting_after=stringReturns the members of a group, as reported by the identity provider, using cursor-based pagination. Each member carries the Clerk user it is linked to, or…
  • GETList directory group role mappings/directories/:directory_id/group_role_mappingsReturns the list of directory group to organization role mappings for a directory, ordered by precedence.
  • PUTReplace directory group role mappings/directories/:directory_id/group_role_mappingsReplaces the entire set of directory group role mappings for a directory. The position of each item in the mappings array determines its precedence (the first…
  • POSTCreate a directory group role mapping/directories/:directory_id/group_role_mappingsCreates a new directory group to organization role mapping for a directory. Mappings can be created while group role mapping is disabled on the directory, but…
  • DELETEDelete a directory group role mapping/directories/:directory_id/group_role_mappings/:mapping_idDeletes a single directory group role mapping. Mappings can be deleted while group role mapping is disabled on the directory, but the change only takes effect…

Admin Portal Link Tokens

  • POSTCreate an Admin Portal Link Token/admin_portal_link_tokens
  • POSTRevoke an Admin Portal Link Token/admin_portal_link_tokens/:adminPortalLinkTokenID/revoke

API details

Base URL
https://api.clerk.com/v1
Authentication
A bearer token in the Authorization header
Operations
264 operations on 184 pathsPOST 97GET 87DELETE 40PATCH 30PUT 10
16 marked deprecated
Main resources
Users 38Billing 18Directories 12Organizations 12Instance Settings 11SCIM Directories 10Machines 9Sessions 9API Keys 8OAuth Applications 8
Response formats
application/json
Description format
OpenAPI 3.0.3, API version 2026-08-20

How to test the Clerk Backend API (2026-08-20) in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Clerk Backend API (2026-08-20) collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Create actor token” (POST /actor_tokens), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Clerk Backend API (2026-08-20)?

The Clerk REST Backend API, meant to be accessed by backend servers. Versions When the API changes in a way that isn't compatible with older versions, a new… It is listed under Identity & security and has 264 endpoints.

Who publishes the Clerk Backend API (2026-08-20)?

It is listed from Clerk's public API description (an OpenAPI document), not published by Clerk on Swastik Codes. Anyone who controls clerk.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Clerk Backend API (2026-08-20)?

Requests go to https://api.clerk.com/v1. Endpoint paths are added to this base URL.

How do I authenticate with the Clerk Backend API (2026-08-20)?

With A bearer token in the Authorization header.

How many endpoints does the Clerk Backend API (2026-08-20) have?

264 operations on 184 paths (97 POST, 87 GET, 40 DELETE, 30 PATCH, 10 PUT). The largest groups are Users, Billing, Directories, Organizations.

Is forking the Clerk Backend API (2026-08-20) free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.