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…
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 - Links
- Documentation · OpenAPI document · Terms of service · Support
- Listed from
- Clerk's published OpenAPI description (clerk/openapi-specs) (MIT)
How to test the Clerk Backend API (2025-11-10) in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- 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.
- 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.
- 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.