Clerk API (unofficial showcase)
PATCH/instance/organization_settings

Update instance organization settings

Updates the organization settings for the instance. Use the available fields to configure organization creation, membership limits, deletion, and domain enrollment; domains_enrollment_modes supports automatic invitations and suggestions. The response returns the updated organization settings.

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

8 body fields

Organization settings to update; all fields are optional.

enabledbooleanoptional
Whether organizations are enabled for the instance.
max_allowed_membershipsintegeroptional
The maximum number of memberships allowed for an organization.
admin_delete_enabledbooleanoptional
Whether an admin can delete an organization through the Frontend API by default.
domains_enabledbooleanoptional
Whether organization domains are enabled.
slug_disabledbooleanoptional
Whether organization slugs are disabled.
domains_enrollment_modesarray<string>optional
Specify which enrollment modes to enable for your Organization Domains. Supported modes are 'automatic_invitation' & 'automatic_suggestion'.
creator_role_idstringoptional
Specify what the default organization role is for an organization creator.
domains_default_role_idstringoptional
Specify what the default organization role is for the organization domains.

6 status codes
200Returns the updated organization settings, including membership limits, domain enrollment modes, role keys, and enabled-state values.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:organization_settings
enabledbooleanrequired
max_allowed_membershipsintegerrequired
max_allowed_rolesintegerrequired
max_role_sets_allowedintegeroptional
max_allowed_domainsintegerrequired
max_allowed_permissionsintegerdeprecatedoptional
max_allowed_permissions is now a no-op, as permissions are now unlimited
creator_rolestringrequired
The role key that a user will be assigned after creating an organization.
admin_delete_enabledbooleanrequired
The default for whether an admin can delete an organization with the Frontend API.
domains_enabledbooleanrequired
slug_disabledbooleanoptional
domains_enrollment_modesarray<string>required
domains_default_rolestringrequired
The role key that it will be used in order to create an organization invitation or suggestion.
initial_role_set_keystringoptional
The role set key that it will be used to create new organizations.
400Returned when the request is unsuccessful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
402Returned when payment is required.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Returned when the request is unsuccessful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Returned when a resource is not found.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned when the request is unsuccessful; a 402 indicates payment is required; a 403 is returned when the request is unsuccessful; a 404 indicates a resource was not found; and a 422 indicates invalid request parameters. domains_enrollment_modes supports automatic_invitation and automatic_suggestion; creator_role_id and domains_default_role_id specify organization roles.