Clerk

Clerk Backend API (2025-11-10)

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 247

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

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

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.

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
247 operations on 172 pathsPOST 92GET 81DELETE 36PATCH 30PUT 8
16 marked deprecated
Main resources
Users 36Billing 18Organizations 12Instance Settings 11Machines 9Sessions 9API Keys 8OAuth Applications 8Email Addresses 7Enterprise Connections 7
Response formats
application/json
Description format
OpenAPI 3.0.3, API version 2025-11-10

How to test the Clerk Backend API (2025-11-10) 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 (2025-11-10) 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 (2025-11-10)?

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 247 endpoints.

Who publishes the Clerk Backend API (2025-11-10)?

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 (2025-11-10)?

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 (2025-11-10)?

With A bearer token in the Authorization header.

How many endpoints does the Clerk Backend API (2025-11-10) have?

247 operations on 172 paths (92 POST, 81 GET, 36 DELETE, 30 PATCH, 8 PUT). The largest groups are Users, Billing, Organizations, Instance Settings.

Is forking the Clerk Backend API (2025-11-10) 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.