Clerk docs

Instance Settings

Modify the settings of your instance.

Fetch the current instance

Fetches the current instance

SecuritybearerAuth
Responses
200

Success

get/instance
Response samples
application/json
{}

Update instance settings

Updates the settings of an instance

SecuritybearerAuth
Request
Request Body schema: application/json
test_mode
boolean or null

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

hibp
boolean or null

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

enhanced_email_deliverability
boolean or null

The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain. This can be helpful if you do not have a high domain reputation.

support_email
string or null
clerk_js_version
string or null
development_origin
string or null
allowed_origins
Array of strings

For browser-like stacks such as browser extensions, Electron (not officially supported), 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_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost.

cookieless_dev
boolean or null
Deprecated

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_syncing
boolean or null

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

Responses
204

Accepted

422

Invalid request parameters

patch/instance
Request samples
application/json
{
  • "test_mode": true,
  • "hibp": true,
  • "enhanced_email_deliverability": true,
  • "support_email": "string",
  • "clerk_js_version": "string",
  • "development_origin": "string",
  • "allowed_origins": [
    ],
  • "cookieless_dev": true,
  • "url_based_session_syncing": true
}
Response samples
application/json
{
  • "errors": [
    ],
  • "meta": { },
  • "clerk_trace_id": "string"
}

Update instance restrictions

Updates the restriction settings of an instance

SecuritybearerAuth
Request
Request Body schema: application/json
allowlist
boolean or null
blocklist
boolean or null
block_email_subaddresses
boolean or null
block_disposable_email_domains
boolean or null
ignore_dots_for_gmail_addresses
boolean or null
Responses
200

Success

402

Payment required

422

Invalid request parameters

patch/instance/restrictions
Request samples
application/json
{
  • "allowlist": true,
  • "blocklist": true,
  • "block_email_subaddresses": true,
  • "block_disposable_email_domains": true,
  • "ignore_dots_for_gmail_addresses": true
}
Response samples
application/json
{
  • "object": "instance_restrictions",
  • "allowlist": true,
  • "blocklist": true,
  • "block_email_subaddresses": true,
  • "block_disposable_email_domains": true,
  • "ignore_dots_for_gmail_addresses": true
}

Update instance organization settings

Updates the organization settings of the instance

SecuritybearerAuth
Request
Request Body schema: application/json
enabled
boolean or null
max_allowed_memberships
integer or null
admin_delete_enabled
boolean or null
domains_enabled
boolean or null
domains_enrollment_modes
Array of strings

Specify which enrollment modes to enable for your Organization Domains. Supported modes are 'automatic_invitation' & 'automatic_suggestion'.

creator_role_id
string or null

Specify what the default organization role is for an organization creator.

domains_default_role_id
string or null

Specify what the default organization role is for the organization domains.

Responses
200

Success

400

Request was not successful

402

Payment required

404

Resource not found

422

Invalid request parameters

patch/instance/organization_settings
Request samples
application/json
{
  • "enabled": true,
  • "max_allowed_memberships": 0,
  • "admin_delete_enabled": true,
  • "domains_enabled": true,
  • "domains_enrollment_modes": [
    ],
  • "creator_role_id": "string",
  • "domains_default_role_id": "string"
}
Response samples
application/json
{
  • "object": "organization_settings",
  • "enabled": true,
  • "max_allowed_memberships": 0,
  • "max_allowed_roles": 0,
  • "max_allowed_permissions": 0,
  • "creator_role": "string",
  • "admin_delete_enabled": true,
  • "domains_enabled": true,
  • "domains_enrollment_modes": [
    ],
  • "domains_default_role": "string"
}
➔ Next to Invitations