Clerk API (unofficial showcase)
PATCH/beta_features/instance_settings

Update instance authentication settings

Updates instance authentication settings, including allowlist restrictions, the sender address for authentication emails, progressive sign-up, and test mode. Set from_email_address to an alphanumeric local part only; restricted_to_allowlist defaults to false when omitted, and test mode defaults to true for development instances.

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

4 body fields

Optional instance authentication settings; supply the fields you want to change.

restricted_to_allowlistbooleanoptional
Whether sign up is restricted to email addresses, phone numbers and usernames that are on the allowlist.
Default:false
from_email_addressstringoptional
The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent. Only alphanumeric values are allowed. Note that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`).
progressive_sign_upbooleanoptional
Enable the Progressive Sign Up algorithm. This feature is deprecated, please contact support if you need assistance.
test_modebooleanoptional
Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances.

3 status codes
200Returns the updated instance settings, including the allowlist restriction, email sender local part, and progressive sign-up setting.
objectstringoptional
String representing the object's type. Objects of the same type share the same value.
Allowed:instance_settings
idstringoptional
restricted_to_allowlistbooleanoptional
from_email_addressstringoptional
progressive_sign_upbooleanoptional
enhanced_email_deliverabilitybooleandeprecatedoptional
Deprecated. This setting is retired and no longer affects email delivery; all email is sent through the instance's configured email sending domain. The field is preserved for API compatibility only and will be removed in a future version.
402Returned when payment is required to update instance settings.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when a setting value fails request validation.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 402 is returned when payment is required to update the instance settings. A 422 is returned when a setting value is invalid; from_email_address must contain only alphanumeric characters and only the email address's local part.