Clerk

Clerk Frontend API

The Clerk REST Frontend API, meant to be accessed from a browser or native environment. This is a Form Based API and all the data must be sent and formatted…

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 Frontend API, meant to be accessed from a browser or native environment.

This is a Form Based API and all the data must be sent and formatted according to the application/x-www-form-urlencoded content type.

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. 2021-02-05. For more information, please see Clerk API Versions.

Using the Try It Console

The Try It feature of the docs only works for Development Instances when using the DevBrowser security scheme.
To use it, first generate a dev instance token from the /v1/dev_browser endpoint.

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

Endpoints 216

DevBrowser

  • POSTCreate a Dev Browser token/v1/dev_browserGenerate a Dev Browser API token. This is used to authenticate Development Instances with the DevBrowser scheme. It must be set before making any request to a…

Well Known

  • GETGet Android Asset Links/.well-known/assetlinks.jsonGet Android asset links for universal/deep linking
  • GETJWKS/.well-known/jwks.jsonRetrieve the JSON Web Key Set of the instance
  • GETApple App Site Association/.well-known/apple-app-site-associationRetrieve the Apple App Site Association file of the instance
  • GETBasic OpenID Configuration Payload/.well-known/openid-configurationGet a basic OpenID configuration payload
  • GETOAuth 2.0 Authorization Server Metadata/.well-known/oauth-authorization-serverGet the OAuth 2.0 Authorization Server Metadata according to RFC 8414
  • GETWebAuthn Related Origins/.well-known/webauthnGet the WebAuthn Related Origin Requests document. Only available when the instance uses the auth_host passkey RP ID strategy; returns a not found error…

Health

  • GETGet Health/v1/healthGet Health

OAuth2 Identity Provider

  • GETRequest OAuth2 authorization/oauth/authorize?response_type=code&client_id=string&redirect_uri=https://example.com&scope=string&state=string&prompt=none&code_challenge=string&code_challenge_method=S256&response_mode=query&nonce=string&resource=https://example.comRequest OAuth2 authorization. If successful, receive authorization grant via redirect.
  • POSTRequest OAuth2 authorization/oauth/authorizeRequest OAuth2 authorization. If successful, receive authorization grant via redirect.
  • POSTRegister OAuth 2.0 Client/oauth/registerRegisters a new OAuth 2.0 client with the authorization server according to RFC 7591 (OAuth 2.0 Dynamic Client Registration Protocol). This endpoint allows…
  • POSTStart a device authorization request/oauth/device_authorizationStarts an OAuth 2.0 Device Authorization Grant (RFC 8628). Display the returned user_code and verification_uri, then poll /oauth/token with the returned…
  • POSTGet OAuth2 token/oauth/tokenExchange an authorization grant for OAuth2 tokens (access token, refresh token, and optionally ID token). This endpoint implements the OAuth 2.0 Token…
  • GETGet user info after OAuth2 flow/oauth/userinfoGet user info in exchange for a valid OAuth2 access token.
  • POSTGet user info after OAuth2 flow/oauth/userinfoGet user info in exchange for a valid OAuth2 access token.
  • POSTGet information for an access or refresh token/oauth/token_infoGet information for an access or refresh token
  • POSTRevoke OAuth2 token/oauth/token/revokeRevoke OAuth2 token by token. Authentication Confidential clients: Must authenticate using HTTP Basic Authentication with Client ID as username and Client…
  • GETGet consent information/v1/me/oauth/consent/:client_id?scope=string&redirect_uri=https://example.comReturns the scopes for a given OAuth Application Client ID. An optional scope query parameter can restrict the returned scopes to only those requested. The…
  • POSTSubmit OAuth2 consent decision/v1/me/oauth/consent/:client_idSubmits the user's consent decision for an OAuth2 authorization request. This endpoint allows building custom consent portals as a replacement for the default…
  • POSTSubmit an OAuth2 device authorization decision/v1/me/oauth/deviceApproves or denies a pending OAuth2 device authorization for the authenticated user.
  • POSTLook up an OAuth2 device authorization/v1/me/oauth/device/lookupReturns the OAuth application and requested scopes associated with a user code.

OAuth2 Callbacks

  • GETOAuth Callback/v1/oauth_callback?scope=string&code=string&state=string&error=stringThe endpoint where the OAuth providers redirect to after a successful authentication attempt.
  • POSTOAuth Post Callback/v1/oauth_callbackConverts a POST to a GET, because if it's a POST coming from an external account. This is necessary because some providers (e.g. Apple) issue a POST instead…
  • GETProvider OAuth Callback/v1/sso/:providerKey/callback?scope=string&code=string&state=string&error=stringThe endpoint where a custom OAuth provider with a provider-specific callback redirects to after an authentication attempt. The flow's state must belong to the…
  • POSTProvider OAuth Post Callback/v1/sso/:providerKey/callbackConverts a POST to a GET on the same path, for providers that issue a POST instead of a GET request.

SAML

  • GETSAML Metadata/v1/saml/metadata/:saml_connection_id.xmlThe Service Provider's SAML metadata
  • POSTSAML ACS/v1/saml/acs/:saml_connection_idThe SAML Assertion Consumer Service (ACS) endpoint, which processes SAML Responses by the IdP.

Client

  • GETGet Current Client/v1/clientReturns the current client that is present either in the browser cookies or authorization header.
  • PUTCreate New Client/v1/clientCreates a new Client and sets it either in the response cookies or the response authorization header.
  • POSTCreate New Client/v1/clientCreates a new Client and sets it either in the response cookies or the response authorization header.
  • DELETEDelete Client's Sessions/v1/clientEnds all Sessions of the Current Client
  • GETGenerate and return a new session token for a given client./v1/client/handshake?redirect_url=string&format=token&organization_id=string&satellite_fapi=stringWhen the authentication status cannot be determined from the current session token, we initiate a handshake to refresh the token and send it back to the…
  • GETCreate session from agent task/v1/agents/tasks?ticket=stringCreates a new session directly from an agent task without requiring navigation to the sign-in page. Agent tasks are single-use tokens created via the Backend…

Sessions

  • DELETERemove client's sessions/v1/client/sessions?sign_out_redirect_url=https://example.comRemoves all the sessions of the current client without removing the __client cookie
  • GETGet Session/v1/client/sessions/:session_idReturns the session with the given id
  • POSTTouch session/v1/client/sessions/:session_id/touchSpecify the active session for the client. When force organization selection is enabled and active_organization_id is sent as null or empty string, the…
  • POSTEnd Session/v1/client/sessions/:session_id/endMarks the given session as ended.
  • POSTRemove Session/v1/client/sessions/:session_id/removeDelete the given session.
  • POSTCreate Session Token/v1/client/sessions/:session_id/tokensCreate a session JWT for the authenticated requested user. When force organization selection is enabled and organization_id is sent as null or empty string,…
  • POSTCreate Session Token With JWT Template/v1/client/sessions/:session_id/tokens/:template_nameCreate a session JWT for the authenticated requested user.
  • POSTStart a new session reverification/v1/client/sessions/:session_id/verifyStart a new session reverification flow by providing a verification level. If the requested level equals 'secondFactor' or 'multiFactor' and the associated…
  • POSTPrepare session reverification first factor/v1/client/sessions/:session_id/verify/prepare_first_factorPrepare the first factor verification. Depending on the strategy, this request will do something different. Parameter actions: If the strategy equals…
  • POSTAttempt session reverification first factor/v1/client/sessions/:session_id/verify/attempt_first_factorAttempt the first factor verification. Requires the first factor verification to be prepared, unless you're using a password. Parameter rules: If the strategy…
  • POSTPrepare session reverification second factor/v1/client/sessions/:session_id/verify/prepare_second_factorPrepare the second factor verification. Requires the status to be equal to needs_second_factor.
  • POSTAttempt session reverification second factor/v1/client/sessions/:session_id/verify/attempt_second_factorAttempt the second factor verification. Requires the status to be equal to needs_second_factor and for the preparation step to have been called.

Sign Ins

  • POSTCreate a new Sign In or replace the current one./v1/client/sign_insCreates or replaces the current Sign in object. In order to authenticate a Sign in in as few requests as possible, you can pass in parameters to this request…
  • GETRetrieve sign-in/v1/client/sign_ins/:sign_in_idReturns the sign-in with the given ID. The sign in is returned only if it belongs to the requesting client and is not abandoned.
  • POSTReset password on sign-in/v1/client/sign_ins/:sign_in_id/reset_passwordReset password on sign-in.
  • POSTPrepare First Factor Verification/v1/client/sign_ins/:sign_in_id/prepare_first_factorPrepares the verification object for the identified Sign in. This step authenticates that the user is who they say they are. Depending on the strategy, this…
  • POSTAttempt First Factor Verification/v1/client/sign_ins/:sign_in_id/attempt_first_factorAttempt the first verification. Requires the sign in attempt to be identified, and the first factor verification to be prepared, unless you're using a…
  • POSTPrepare Second Factor Verification/v1/client/sign_ins/:sign_in_id/prepare_second_factorPrepare the second verification. Requires the sign in attempt status to be equal to needs_second_factor or needs_client_trust.
  • POSTAttempt Second Factor Verification/v1/client/sign_ins/:sign_in_id/attempt_second_factorAttempt the second verification. Requires the sign in attempt status to be equal to needs_second_factor or needs_client_trust, and for the preparation step to…
  • GETAccept ticket/v1/tickets/accept?ticket=stringParses a ticket JWT and performs the necessary actions depending on the ticket's source type. Depending on the ticket source type, a successful response can…
  • GETAttempt Email Link Verification/v1/verify?token=stringAttempt to verify a verification with email_link strategy.

Sign Ups

  • POSTCreate Sign-up/v1/client/sign_upsCreates or replaces the sign-up on the current Client object.
  • GETGet Sign-up/v1/client/sign_ups/:sign_up_idReturns the sign-up by ID. Must be associated with the current Client object.
  • PATCHUpdate Sign-up/v1/client/sign_ups/:sign_up_idUpdates the sign-up object specified by ID, with the supplied parameters.
  • POSTPrepare Sign-up Identification Verification/v1/client/sign_ups/:sign_up_id/prepare_verificationPrepares verification for the sign-up specified by {id}. Depending on the given strategy, the API will prepare the verification for the current sign-up. In…
  • POSTAttempt Sign-up Identification Verification/v1/client/sign_ups/:sign_up_id/attempt_verificationAttempts to verify the identification that corresponds to the given strategy using the given verification code.

User

  • GETGet User/v1/meReturns all attributes of the current user.
  • DELETEDelete User/v1/meDelete the current user.
  • PATCHUpdate User/v1/meUpdate the current user with the given attributes. unsafe_metadata is not accepted on this endpoint as of API version 2026-05-12. Use PATCH /v1/me/metadata to…
  • PATCHMerge and update the current user's metadata/v1/me/metadataUpdate the current user's metadata attributes by merging existing values with the provided parameters. This endpoint behaves differently than the *Update…
  • POSTcreateServiceToken/v1/me/tokens?_clerk_session_id=stringCreate a JWT for the requested user.
  • POSTUpdate Profile Image/v1/me/profile_imageUpdate the current user's profile image.
  • DELETEDelete Profile Image/v1/me/profile_imageRemove the current user's profile image.
  • POSTUpdate Password/v1/me/change_passwordUpdate the current user's password.
  • POSTDelete Password/v1/me/remove_passwordRemoves the current user's password.

Active Sessions

  • GETGet Active Sessions/v1/me/sessions/active?_clerk_session_id=stringReturns all active session for user, including activity information.
  • POSTRevoke given session/v1/me/sessions/:session_id/revoke?_clerk_session_id=stringRevokes given session.
  • GETGet Sessions/v1/me/sessions?_clerk_session_id=stringGet all the sessions of the current user.

Email Addresses

  • GETGet Email Addresses/v1/me/email_addresses?_clerk_session_id=stringRetrieve all the email addresses associated with the current user.
  • POSTCreate Email Address/v1/me/email_addresses?_clerk_session_id=stringAdd an email address to the current user. The address then needs to be verified using the prepare_verification and attempt_verification endpoints.
  • POSTAttempt Email Address Verification/v1/me/email_addresses/:email_id/attempt_verification?_clerk_session_id=stringAttempt to verify an email address that was previously created.
  • POSTPrepare Email Address Verification/v1/me/email_addresses/:email_id/prepare_verification?_clerk_session_id=stringDepending on the given strategy, the API will prepare the verification for the email address. In particular, * for email_code, the API will send a…
  • GETGet Email Address/v1/me/email_addresses/:email_id?_clerk_session_id=stringRetrieve an email address by ID.
  • DELETEDelete email address/v1/me/email_addresses/:email_id?_clerk_session_id=stringDelete an email address by ID.

Phone Numbers

  • GETGet Phone Numbers/v1/me/phone_numbers?_clerk_session_id=stringRetrieve all phone numbers associated with the current user.
  • POSTCreate Phone Number/v1/me/phone_numbers?_clerk_session_id=stringAdd a phone number to the current user. The phone number then needs to be verified using the sms prepare_verification and attempt_verification endpoints.
  • POSTAttempt Phone Number Verification/v1/me/phone_numbers/:phone_number_id/attempt_verification?_clerk_session_id=stringAttempt to verify the given phone number using the code sent during the prepare_verification step.
  • POSTPrepare Phone Number Verification/v1/me/phone_numbers/:phone_number_id/prepare_verification?_clerk_session_id=stringSends an SMS to the phone number with the code needed to verify it.
  • GETRetrieve Phone Number/v1/me/phone_numbers/:phone_number_id?_clerk_session_id=stringRetrieve all properties for the given phone number.
  • DELETEDelete Phone Number/v1/me/phone_numbers/:phone_number_id?_clerk_session_id=stringDeletes the phone number with the given ID.
  • PATCHUpdate Phone Number/v1/me/phone_numbers/:phone_number_id?_clerk_session_id=stringUpdate the properties of the given phone number.

Web3 Wallets

  • GETGet All Web3 Wallets/v1/me/web3_wallets?_clerk_session_id=stringRetrieve all web3 wallets associated with the current user.
  • POSTCreate Web3 Wallet/v1/me/web3_wallets?_clerk_session_id=stringCreate a new web3 wallet.
  • GETGet Web3 Wallet/v1/me/web3_wallets/:web3_wallet_idRetrieve all properties associated with a specific web3 wallet.
  • DELETEDelete Web3 Wallet/v1/me/web3_wallets/:web3_wallet_idDelete a web3 wallet by ID.
  • POSTPrepare Web3 Wallet Verification/v1/me/web3_wallets/:web3_wallet_id/prepare_verificationPrepares verification for the provided web3 wallet.
  • POSTAttempt Web3 Wallet Verification/v1/me/web3_wallets/:web3_wallet_id/attempt_verificationAttempts to verify the provided web3 wallet.

Passkeys

  • POSTCreate Passkey/v1/me/passkeys?_clerk_session_id=stringCreate a new passkey.
  • GETGet Passkey/v1/me/passkeys/:passkey_idRetrieve all properties associated with a specific passkey.
  • DELETEDelete Passkey/v1/me/passkeys/:passkey_idDelete a passkey by ID.
  • PATCHUpdate Passkey/v1/me/passkeys/:passkey_idUpdate properties of a specific passkey.
  • POSTAttempt Passkey Verification/v1/me/passkeys/:passkey_id/attempt_verificationAttempts to verify the provided passkey.

Trusted Devices

  • POSTValidate Trusted Device Sign-In Credential/v1/client/trusted_devices/validateDeprecated. Validates that a local trusted-device credential can be used by the current native client.
  • GETList Trusted Devices/v1/me/trusted_devicesDeprecated. Retrieve active trusted-device credentials associated with the current user.
  • POSTPrepare Trusted Device Enrollment/v1/me/trusted_devices/prepareDeprecated. Issues a one-time challenge for enrolling a native trusted-device credential.
  • POSTAttempt Trusted Device Enrollment/v1/me/trusted_devices/attemptDeprecated. Verifies a signed enrollment challenge and creates a trusted-device credential.
  • DELETERevoke Trusted Device/v1/me/trusted_devices/:trusted_device_idDeprecated. Revokes a trusted-device credential so it can no longer authenticate.

Biometric Credentials

  • POSTValidate Biometric Sign-In Credential/v1/client/biometric_credentials/validateValidates that a local biometric credential can be used by the current native client.
  • GETList Biometric Credentials/v1/me/biometric_credentialsRetrieve active biometric credentials associated with the current user.
  • POSTPrepare Biometric Credential Enrollment/v1/me/biometric_credentials/prepareIssues a one-time challenge for enrolling a native biometric credential.
  • POSTAttempt Biometric Credential Enrollment/v1/me/biometric_credentials/attemptVerifies a signed enrollment challenge and creates a biometric credential.
  • DELETERevoke Biometric Credential/v1/me/biometric_credentials/:biometric_credential_idRevokes a biometric credential so it can no longer authenticate.

External Accounts

  • POSTConnect OAuth Accounts/v1/me/external_accountsConnect a new External Account from the OAuth providers enabled.
  • PATCHReauthorize External Account/v1/me/external_accounts/:external_account_id/reauthorizeReauthorize an external account by ID.
  • DELETEDelete External Account/v1/me/external_accounts/:external_account_idDelete an external account by ID.
  • DELETERevoke OAuth tokens/v1/me/external_accounts/:external_account_id/tokensRevoke the OAuth access and refresh token of an external account by ID, if supported by the provider.

TOTP

  • POSTCreate TOTP/v1/me/totpInitializes TOTP by generating a new secret. This then needs to be added to an authenticator app and verified. A user can have only one TOTP secret and this…
  • DELETEDelete TOTP/v1/me/totpDeletes the current TOTP secret. This will invalidate all authenticators that where previously added.
  • POSTAttempt TOTP Verification/v1/me/totp/attempt_verificationAttempts to verify the TOTP secret previously created using a code from an authenticator.

Backup Codes

  • POSTCreate Backup Codes/v1/me/backup_codesCreate two factor authentication backup codes for the current user. A two factor authentication method must be enabled for the environment. Otherwise the…

Organizations Memberships

  • GETGet Organization Memberships/v1/me/organization_memberships?limit=10&offset=0&paginated=trueGet a list of the organization memberships of the current user.
  • DELETEDelete Organization Membership/v1/me/organization_memberships/:organization_idDelete the membership of the given organization.
  • GETGet Current User's Organization Invitations/v1/me/organization_invitations?limit=10&offset=0&status=stringGet a list of the organization invitations of the current user.
  • POSTAccept Organization invitation/v1/me/organization_invitations/:invitation_id/acceptAccept an organization invitation for the current user.
  • GETGet Organization Suggestions/v1/me/organization_suggestions?limit=10&offset=0&status=stringGet a list of the organization suggestions of the current user.
  • POSTAccept Organization Suggestion/v1/me/organization_suggestions/:suggestion_id/acceptAccept an organization suggestion for the current user.

Organization

  • POSTCreate Organization/v1/organizationsCreate an organization and add the current user as admin.
  • GETGet Organization/v1/organizations/:organization_idRetrieve all properties of an organization that the current user is member of.
  • DELETEDelete Organization/v1/organizations/:organization_idDelete the given organization. The current user must be an admin in the organization.
  • PATCHUpdate Organization/v1/organizations/:organization_idUpdate the given properties of an organization. The current user must be an admin in the organization.
  • PUTUpdate Organization Logo/v1/organizations/:organization_id/logoUpdate the organization logo. The current user must be an admin in the organization.
  • DELETEDelete Organization Logo/v1/organizations/:organization_id/logoDelete the organization logo. The current user must be an admin in the organization.

Organization Creation Defaults

  • GETGet organization creation defaults/v1/me/organization_creation_defaultsGet suggested organization name and other defaults for creating a new organization. Returns suggestions based on the user's email domain or configured naming…

Invitations

  • GETGet All Organization Invitations/v1/organizations/:organization_id/invitations?limit=10&offset=0&status=pendingRetrieve all invitations for an organization. The current user must have permissions to manage the members of the organization.
  • POSTCreate Organization Invitation/v1/organizations/:organization_id/invitationsCreate an invitation for a user to join an organization. The current user must have permissions to manage the members of the organization.
  • POSTBulk Create Organization Invitations/v1/organizations/:organization_id/invitations/bulkCreate an invitation for a user to join an organization. The current user must have permissions to manage the members of the organization.
  • GETGet All Pending Organization Invitations/v1/organizations/:organization_id/invitations/pendingDeprecated. Get a list of pending invitations for an organization. This endpoint is deprecated. Instead use the…
  • POSTRevoke Pending Organization Invitation/v1/organizations/:organization_id/invitations/:invitation_id/revokeRevoke a pending organization invitation. The current user must have permissions to manage the members of the organization.

Members

  • GETGet All Organization Members/v1/organizations/:organization_id/memberships?limit=10&offset=0&paginated=true&query=string&role=stringRetrieve all members of an organization. The current user must have permissions to manage the members of the organization.
  • POSTCreate Organization Membership/v1/organizations/:organization_id/membershipsCreate a new organization membership. The current user must have permissions to manage the members of the organization.
  • DELETERemove Organization Member/v1/organizations/:organization_id/memberships/:user_idRemove a member from an organization. The current user must have permissions to manage the members of the organization.
  • PATCHUpdate Organization Membership/v1/organizations/:organization_id/memberships/:user_idUpdate the attributes of an organization membership for a specific user. The current user must have permissions to manage the members of the organization.

Membership Requests

  • GETGet Organization Membership Requests/v1/organizations/:organization_id/membership_requests?limit=10&offset=0&status=stringRetrieve a list of all membership requests of an organization. The current user must have permissions to manage the members of the organization.
  • POSTAccept Organization Membership Request/v1/organizations/:organization_id/membership_requests/:request_id/acceptAccepts an organization membership request. The current user must have permissions to manage the members of the organization.
  • POSTReject Organization Membership Request/v1/organizations/:organization_id/membership_requests/:request_id/rejectRejects an organization membership request The current user must have permissions to manage the members of the organization.

Domains

  • GETGet All Organization Domains/v1/organizations/:organization_id/domains?limit=10&offset=0&verified=true&enrollment_mode=stringRetrieves a list of all the domains in an organization The current user must have permissions to manage the domains of the organization.
  • POSTCreate Organization Domain/v1/organizations/:organization_id/domainsCreate a new organization domain. The current user must have permissions to manage the domains of the organization.
  • POSTBulk Create Organization Domains/v1/organizations/:organization_id/domains/bulkCreates up to 10 organization domains by name. Duplicate names in the request are skipped. The response is a partial-success payload: successfully created…
  • POSTBulk Prepare Organization Domain Ownership Verification/v1/organizations/:organization_id/domains/prepare_ownership_verification/bulkCollection-level bulk counterpart of the single /domains/{domain_id}/prepare_ownership_verification endpoint. Accepts a set of organization_domain_ids and…
  • POSTBulk Attempt Organization Domain Ownership Verification/v1/organizations/:organization_id/domains/attempt_ownership_verification/bulkCollection-level bulk counterpart of the single /domains/{domain_id}/attempt_ownership_verification endpoint. Accepts a set of organization_domain_ids and…
  • GETGet Organization Domain/v1/organizations/:organization_id/domains/:domain_idRetrieve all properties for a domain of an organization. The current user must have permissions to manage the domains of the organization.
  • DELETEDelete Organization Domain/v1/organizations/:organization_id/domains/:domain_idRemove a domain from an organization. The current user must have permissions to manage the domains of the organization.
  • POSTUpdate Organization Enrollment Mode/v1/organizations/:organization_id/domains/:domain_id/update_enrollment_modeUpdate the enrollment mode for an organization domain. This can be either automatic_invitation or automatic_suggestion. The current user must have permissions…
  • POSTPrepare Organization Domain Affiliation Verification/v1/organizations/:organization_id/domains/:domain_id/prepare_affiliation_verificationPrepares affiliation verification for an organization domain. The current user must have permissions to manage the domains of the organization.
  • POSTAttempt Organization Domain Affiliation Verification/v1/organizations/:organization_id/domains/:domain_id/attempt_affiliation_verificationAttempts affiliation verification for organization domain The current user must have permissions to manage the domains of the organization.
  • POSTPrepare Organization Domain Ownership Verification/v1/organizations/:organization_id/domains/:domain_id/prepare_ownership_verificationIssues a fresh TXT challenge for the organization domain. The plaintext TXT record value is returned in the response payload and is only stored as a bcrypt…
  • POSTAttempt Organization Domain Ownership Verification/v1/organizations/:organization_id/domains/:domain_id/attempt_ownership_verificationResolves the TXT record for the organization domain and, on a successful match against the outstanding challenge, marks the domain as ownership-verified and…

Environment

  • GETGet environment/v1/environmentGet the current environment. The environment contains information about the settings and features enabled for the current instance.
  • PATCHUpdate environment/v1/environmentUpdate environment using request origin

Waitlist

  • POSTJoin Waitlist/v1/waitlistAdds an email address to the waitlist. If the email is already on the waitlist, the request will still succeed, returning the ID of the existing waitlist entry.

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
  • PATCHUpdate an API Key/api_keys/:apiKeyID
  • POSTRevoke an API Key/api_keys/:apiKeyID/revoke

Enterprise Connections

  • GETList enterprise connections for the active organization/v1/organizations/:organizationID/enterprise_connections?_clerk_session_id=stringReturns the active enterprise connections visible to the requesting user within the active organization context. The active organization is taken from the…
  • POSTCreate enterprise connection for an organization/v1/organizations/:organizationID/enterprise_connections?_clerk_session_id=stringCreates an enterprise connection bound to the organization in the URL path. The caller's session must be pinned to that organization and the caller must hold…
  • DELETEDelete enterprise connection for an organization/v1/organizations/:organizationID/enterprise_connections/:enterprise_connection_id?_clerk_session_id=stringDeletes an enterprise connection bound to the organization in the URL path. The caller's session must be pinned to that organization and the caller must hold…
  • PATCHUpdate enterprise connection for an organization/v1/organizations/:organizationID/enterprise_connections/:enterprise_connection_id?_clerk_session_id=stringUpdates an enterprise connection bound to the organization in the URL path. The caller's session must be pinned to that organization and the caller must hold…
  • GETList enterprise connection test runs for an organization/v1/organizations/:organizationID/enterprise_connections/:enterprise_connection_id/test_runs?_clerk_session_id=string&status=pending&limit=10&offset=0&paginated=trueReturns a paginated list of SAML or OIDC debug test runs for an organization-bound enterprise connection.
  • POSTCreate enterprise connection test run for an organization/v1/organizations/:organizationID/enterprise_connections/:enterprise_connection_id/test_runs?_clerk_session_id=stringReturns a short-lived URL that starts the IdP test flow for an organization-bound enterprise connection.
  • GETList enterprise connections for the current user/v1/me/enterprise_connections?_clerk_session_id=stringDeprecated. Deprecated. Use GET /v1/organizations/{organizationID}/enterprise_connections instead. Returns active enterprise connections on the instance whose…
  • POSTCreate enterprise connection/v1/me/enterprise_connections?_clerk_session_id=stringDeprecated. Deprecated. Use POST /v1/organizations/{organizationID}/enterprise_connections instead. Creates an enterprise connection for the instance.
  • DELETEDelete enterprise connection/v1/me/enterprise_connections/:enterprise_connection_id?_clerk_session_id=stringDeprecated. Deprecated. Use DELETE /v1/organizations/{organizationID}/enterprise_connections/{enterprise_connection_id} instead. Deletes an enterprise…
  • PATCHUpdate enterprise connection/v1/me/enterprise_connections/:enterprise_connection_id?_clerk_session_id=stringDeprecated. Deprecated. Use PATCH /v1/organizations/{organizationID}/enterprise_connections/{enterprise_connection_id} instead. Updates an enterprise…
  • GETList enterprise connection test runs/v1/me/enterprise_connections/:enterprise_connection_id/test_runs?_clerk_session_id=string&status=pending&limit=10&offset=0&paginated=trueDeprecated. Deprecated. Use GET /v1/organizations/{organizationID}/enterprise_connections/{enterprise_connection_id}/test_runs instead. Returns a paginated…
  • POSTCreate enterprise connection test run/v1/me/enterprise_connections/:enterprise_connection_id/test_runs?_clerk_session_id=stringDeprecated. Deprecated. Use POST /v1/organizations/{organizationID}/enterprise_connections/{enterprise_connection_id}/test_runs instead. Returns a short-lived…
  • GETInitiate enterprise connection test run/v1/enterprise_connections/:enterpriseConnectionID/init_test_run?ticket=stringInitiates a test run for an enterprise connection. Validates the provided ticket and redirects to the Identity Provider for authentication.
  • GETGet enterprise connection test run result/v1/enterprise_connections/:enterpriseConnectionID/test_runs/:testRunID?token=stringReturns the result of an enterprise connection test run as an HTML page. Displays success or error status with detailed information about the test run.

SSO Bypass

  • GETList the organization's SSO bypass allowlist/v1/organizations/:organizationID/sso_bypass_allowlist_users?_clerk_session_id=stringReturns the members who may verify an email code instead of reaching their identity provider when one of the organization's enterprise connections is…
  • POSTAdd a member to the organization's SSO bypass allowlist/v1/organizations/:organizationID/sso_bypass_allowlist_users?_clerk_session_id=stringPuts a member on the allowlist. The request is rejected unless the user is a member of the organization and holds a verified email address on a domain one of…
  • POSTAdd up to 100 members to the organization's SSO bypass allowlist/v1/organizations/:organizationID/sso_bypass_allowlist_users/bulk?_clerk_session_id=stringPuts a batch of members on the allowlist in one request. The response is a partial-success payload: members who were added, or were already on the list, are…
  • DELETERemove a member from the organization's SSO bypass allowlist/v1/organizations/:organizationID/sso_bypass_allowlist_users/:user_id?_clerk_session_id=stringRemoves the user from the allowlist of every enterprise connection the organization owns. The caller must hold the org:sys_entconns_sso_bypass:manage…

Plans

  • GETList billing plans/v1/billing/plans?payer_type=userReturns a list of all publicly visible billing plans.
  • GETGet a billing plan/v1/billing/plans/:planIdOrSlugReturns a billing plan by ID or slug.

Subscriptions

  • GETGet user's main billing subscription/v1/me/billing/subscriptionReturns the main billing subscription for the current user.
  • GETGet organization's billing subscription/v1/organizations/:organizationID/billing/subscriptionReturns the billing subscription for the organization.

Subscription Items

  • GETList user's subscription items/v1/me/billing/subscription_items?limit=10&offset=0&paginated=trueReturns a list of subscription items for the current user.
  • DELETECancel user's subscription item/v1/me/billing/subscription_items/:subscriptionItemIDCancels a subscription item for the current user.
  • GETList organization's subscription items/v1/organizations/:organizationID/billing/subscription_itemsReturns a list of subscription items for the organization.
  • DELETECancel organization's subscription item/v1/organizations/:organizationID/billing/subscription_items/:subscriptionItemIDCancels a subscription item for the organization.

Checkouts

  • POSTCreate billing checkout/v1/me/billing/checkoutsCreates a new billing checkout for the current user.
  • GETGet billing checkout/v1/me/billing/checkouts/:checkoutIDReturns a billing checkout for the current user.
  • PATCHUpdate billing checkout/v1/me/billing/checkouts/:checkoutIDApplies or removes a promo code on an in-progress billing checkout for the current user. A non-blank promo_code applies the code; a blank value clears it.
  • PATCHConfirm billing checkout/v1/me/billing/checkouts/:checkoutID/confirmConfirms a billing checkout for the current user.
  • POSTCreate organization billing checkout/v1/organizations/:organizationID/billing/checkoutsCreates a new billing checkout for the organization.
  • GETGet organization billing checkout/v1/organizations/:organizationID/billing/checkouts/:checkoutIDReturns a billing checkout for the organization.
  • PATCHUpdate organization billing checkout/v1/organizations/:organizationID/billing/checkouts/:checkoutIDApplies or removes a promo code on an in-progress billing checkout for the organization. A non-blank promo_code applies the code; a blank value clears it.
  • PATCHConfirm organization billing checkout/v1/organizations/:organizationID/billing/checkouts/:checkoutID/confirmConfirms a billing checkout for the organization.

Payment Methods

  • GETList user payment methods/v1/me/billing/payment_methods?limit=10&offset=0&paginated=trueReturns a list of all payment methods for the current user.
  • POSTCreate user payment method/v1/me/billing/payment_methodsCreates a new payment method for the current user.
  • POSTInitialize user payment method/v1/me/billing/payment_methods/initializeInitializes a payment method setup process for the current user.
  • DELETEDelete user payment method/v1/me/billing/payment_methods/:paymentMethodIDDeletes a specific payment method for the current user.
  • PUTSet user default payment method/v1/me/billing/payers/default_payment_methodSets the default payment method for the current user.
  • GETList organization payment methods/v1/organizations/:organizationID/billing/payment_methodsLists all payment methods for the organization.
  • POSTCreate organization payment method/v1/organizations/:organizationID/billing/payment_methodsCreates a new payment method for the organization.
  • POSTInitialize organization payment method/v1/organizations/:organizationID/billing/payment_methods/initializeInitializes a payment method for the organization.
  • DELETEDelete organization payment method/v1/organizations/:organizationID/billing/payment_methods/:paymentMethodIDDeletes a payment method for the organization.
  • PUTSet organization default payment method/v1/organizations/:organizationID/billing/payers/default_payment_methodSets the default payment method for the organization.

Statements

  • GETList user statements/v1/me/billing/statements?limit=10&offset=0&paginated=trueReturns a list of billing statements for the current user.
  • GETGet user statement/v1/me/billing/statements/:statementIDReturns details of a specific billing statement for the current user.
  • GETList organization statements/v1/organizations/:organizationID/billing/statementsLists all statements for the organization.
  • GETGet organization statement/v1/organizations/:organizationID/billing/statements/:statementIDGets a specific statement for the organization.

Payment Attempts

  • GETList user payment attempts/v1/me/billing/payment_attempts?limit=10&offset=0&paginated=trueReturns a list of payment attempts for the current user.
  • GETGet user payment attempt/v1/me/billing/payment_attempts/:paymentAttemptIDReturns details of a specific payment attempt for the current user.

Roles

  • GETGet Organization Roles/v1/organizations/:organization_id/roles?limit=10&offset=0Retrieve a list of all roles of an organization.

Redirect

  • GETRedirect to a validated URL/v1/redirect?redirect_url=stringValidates and redirects to a safe URL. If no URL is provided, redirects to a default URL.
  • GETGet account portal/v1/account_portalGet users account portal
  • GETGet Proxy Health/v1/proxy-health?domain_id=stringUse this endpoint to check the validity of a proxy configuration for a domain. Pass the instance ID and domain ID as query parameters.
  • GETSync clients across multiple domains/v1/client/sync?link_domain=string&redirect_url=stringStart the syncing process between a satellite and primary domain.
  • GETLink clients across multiple domains/v1/client/link?__clerk_token=stringComplete a syncing process between a satellite and primary domains by linking their clients.
  • POSTPost Dev Browser init set cookie/v1/dev_browser/set_first_party_cookiepost dev_browser/set_first_party_cookie
  • GETInitialize dev browser for development and staging instances/v1/dev_browser/init?origin=stringget dev_browser/init
  • GETSet the Clear-Site-Data header/v1/clear-site-dataClear browsing data (cookies, storage, cache) associated with the requesting website

API details

Base URL
https://{domain}.clerk.accounts.dev
Authentication
An API key in the __client cookie
An API key in the __dev_session query parameter
A bearer token in the Authorization header
An API key in the _is_native query parameter
HTTP Basic authentication (username and password)
Operations
216 operations on 173 pathsPOST 94GET 77DELETE 25PATCH 16PUT 4
12 marked deprecated
Main resources
Enterprise Connections 14OAuth2 Identity Provider 13Domains 12Sessions 12Payment Methods 10Sign Ins 9User 9Checkouts 8Phone Numbers 7Client 6
Response formats
application/json text/html
Description format
OpenAPI 3.0.3, API version v1

How to test the Clerk Frontend API 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 Frontend API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the __client cookie. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Create a Dev Browser token” (POST /v1/dev_browser), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Clerk Frontend API?

The Clerk REST Frontend API, meant to be accessed from a browser or native environment. This is a Form Based API and all the data must be sent and formatted… It is listed under Identity & security and has 216 endpoints.

Who publishes the Clerk Frontend API?

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 Frontend API?

Requests go to https://{domain}.clerk.accounts.dev. Endpoint paths are added to this base URL.

How do I authenticate with the Clerk Frontend API?

It accepts 5 methods: an API key in the __client cookie; an API key in the __dev_session query parameter; A bearer token in the Authorization header; an API key in the _is_native query parameter; HTTP Basic authentication (username and password).

How many endpoints does the Clerk Frontend API have?

216 operations on 173 paths (94 POST, 77 GET, 25 DELETE, 16 PATCH, 4 PUT). The largest groups are Enterprise Connections, OAuth2 Identity Provider, Domains, Sessions.

Is forking the Clerk Frontend API 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.