Instance Settings

Update instance settings

Changed on

Updates the settings of an instance

patch/instance

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/instance
  • Auth: HTTP bearer

Request body

test_modeboolean nullable

Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances.

hibpboolean nullable

Whether the instance should be using the HIBP service to check passwords for breaches

support_emailstring nullable
clerk_js_versionstring nullable
development_originstring nullable
allowed_originsstring[] nullable

For browser-like stacks such as browser extensions, Electron, or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uuid. For Electron apps using @clerk/electron, the origins are the custom renderer scheme registered with createClerkBridge(), for example my-app://renderer, and, during development, the renderer's dev server origin, for example http://localhost:5173. For Capacitor, the origin is capacitor://localhost. Send an empty array to remove all allowed origins. A null value leaves the current list unchanged.

allowed_subdomainsstring[] nullable

Subdomains of the instance's own domains that may originate requests while subdomain_allowlist_enabled is true. Each entry is either an exact host (app.example.com) or a wildcard anchored on a host beneath one of the instance's domains (*.preview.example.com), which covers every host under that anchor but not the anchor itself. Entries are stored folded to lower case with any trailing dot removed, the form the origin check compares against, so entries differing only in those respects are one entry. Entries already stored are not validated again, so a list read back from the instance can always be written again unchanged. Send an empty array to remove all entries. A null value leaves the current list unchanged. Production instances only.

subdomain_allowlist_enabledboolean nullable

Whether requests from subdomains of the instance's own domains are restricted to allowed_subdomains. When false, every subdomain of the instance's domain is accepted. Production instances only.

cookieless_devboolean nullable

Whether the instance should operate in cookieless development mode (i.e. without third-party cookies). Deprecated: Please use url_based_session_syncing instead.

url_based_session_syncingboolean nullable

Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies).

preferred_sign_in_strategy_when_password_required'password' | 'otp' | '' nullable

When password is required at the instance level, sets the preferred sign-in strategy surfaced to Clerk components. Has no effect when password is not required. Defaults to password. Set to an empty string to clear the override.

Response

Accepted

Changes

  • 2025-11-10b5f30169c3f3Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property became nullable

  • 2025-11-10e3f2b3a1c567Revision changes
    • info

      added the new optional request property