PATCH/instance

Update instance settings

Updates configurable settings for an instance, including browser origins, password breach checks, and sign-in preferences. Supply only the settings you want to change; preferred_sign_in_strategy_when_password_required accepts password, otp, or an empty string.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

11 body fields

Instance settings to update. All fields are optional.

test_modebooleanoptional
Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances.
hibpbooleanoptional
Whether the instance should be using the HIBP service to check passwords for breaches
support_emailstringoptional
The support email address for the instance.
clerk_js_versionstringoptional
The Clerk JavaScript version to use.
development_originstringoptional
The origin to use for development.
allowed_originsarray<string>optional
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_subdomainsarray<string>optional
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_enabledbooleanoptional
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_devbooleandeprecatedoptional
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_syncingbooleanoptional
Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies).
preferred_sign_in_strategy_when_password_requiredstringoptional
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.
Allowed:passwordotp

2 status codes
204Returns no response body after accepting the instance settings update.
422Returned when one or more supplied instance settings are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 422 is returned when a supplied setting is invalid. preferred_sign_in_strategy_when_password_required must be password, otp, or an empty string; the other settings must match their declared types.