Clerk Instance Settings API

openapi: 3.2.0
info:
  title: Clerk Backend Instance Settings API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Backend API, meant to be accessed by backend servers.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see Clerk API Versions.


    Please see https://clerk.com/docs for more information.'
  version: '2026-08-20'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: Instance Settings
  description: Modify the settings of your instance.
paths:
  /instance:
    get:
      operationId: GetInstance
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: get
      summary: Fetch the current instance
      description: Fetches the current instance
      tags:
      - Instance Settings
      responses:
        '200':
          $ref: '#/components/responses/Instance'
    patch:
      operationId: UpdateInstance
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: update
      summary: Update instance settings
      description: Updates the settings of an instance
      tags:
      - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                test_mode:
                  type:
                  - boolean
                  - 'null'
                  description: 'Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.

                    Defaults to true for development instances.'
                hibp:
                  type:
                  - boolean
                  - 'null'
                  description: Whether the instance should be using the HIBP service to check passwords for breaches
                support_email:
                  type:
                  - string
                  - 'null'
                clerk_js_version:
                  type:
                  - string
                  - 'null'
                development_origin:
                  type:
                  - string
                  - 'null'
                allowed_origins:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: '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_subdomains:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: '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_enabled:
                  type:
                  - boolean
                  - 'null'
                  description: 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_dev:
                  type:
                  - boolean
                  - 'null'
                  description: 'Whether the instance should operate in cookieless development mode (i.e. without third-party cookies).

                    Deprecated: Please use `url_based_session_syncing` instead.'
                  deprecated: true
                url_based_session_syncing:
                  type:
                  - boolean
                  - 'null'
                  description: 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:
                  type:
                  - string
                  - 'null'
                  description: 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.
                  enum:
                  - password
                  - otp
                  - ''
                  - null
      responses:
        '204':
          description: Accepted
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /instance/restrictions:
    patch:
      operationId: UpdateInstanceRestrictions
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: updateRestrictions
      summary: Update instance restrictions
      description: Updates the restriction settings of an instance
      tags:
      - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                allowlist:
                  type:
                  - boolean
                  - 'null'
                blocklist:
                  type:
                  - boolean
                  - 'null'
                allowlist_blocklist_disabled_on_sign_in:
                  type:
                  - boolean
                  - 'null'
                block_email_subaddresses:
                  type:
                  - boolean
                  - 'null'
                block_disposable_email_domains:
                  type:
                  - boolean
                  - 'null'
      responses:
        '200':
          $ref: '#/components/responses/InstanceRestrictions'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /instance/protect:
    get:
      operationId: GetInstanceProtect
      summary: Get instance protect settings
      tags:
      - Instance Settings
      responses:
        '200':
          $ref: '#/components/responses/InstanceProtect'
    patch:
      operationId: UpdateInstanceProtect
      summary: Update instance protect settings
      tags:
      - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                rules_enabled:
                  type:
                  - boolean
                  - 'null'
                  description: Set true to enforce Protect rules on this instance. Set false to stop enforcing and return the instance to its default posture, where traffic is still evaluated in shadow but nothing is blocked. This does not remove the instance from Protect.
      responses:
        '200':
          $ref: '#/components/responses/InstanceProtect'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /instance/communication:
    get:
      operationId: GetInstanceCommunication
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: getCommunication
      summary: Get instance communication settings
      description: Retrieves the per-instance SMS communication settings, including the SMS country blocklist.
      tags:
      - Instance Settings
      responses:
        '200':
          $ref: '#/components/responses/InstanceCommunication'
    patch:
      operationId: UpdateInstanceCommunication
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: updateCommunication
      summary: Update instance communication settings
      description: 'Replaces the SMS country blocklist for this instance. Pass the full set of ISO 3166-1

        alpha-2 country codes that should be blocked; codes that aren''t recognized as SMS-tier

        countries are silently dropped from the persisted list. Omitting `blocked_country_codes`

        is a no-op.'
      tags:
      - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                blocked_country_codes:
                  type:
                  - array
                  - 'null'
                  description: ISO 3166-1 alpha-2 country codes to block for SMS delivery. Whole-list replacement. Codes must be uppercase, 2-letter, and unique within the array.
                  maxItems: 250
                  uniqueItems: true
                  items:
                    type: string
                    pattern: ^[A-Z]{2}$
      responses:
        '200':
          $ref: '#/components/responses/InstanceCommunication'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /instance/oauth_application_settings:
    get:
      operationId: GetInstanceOAuthApplicationSettings
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: getOAuthApplicationSettings
      summary: Get OAuth application settings
      description: Retrieves the settings for OAuth applications for the instance (dynamic client registration, JWT access tokens, etc.).
      tags:
      - Instance Settings
      responses:
        '200':
          $ref: '#/components/responses/InstanceOAuthApplicationSettings'
    patch:
      operationId: UpdateInstanceOAuthApplicationSettings
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: updateOAuthApplicationSettings
      summary: Update OAuth application settings
      description: Updates the OAuth application settings for the instance.
      tags:
      - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                dynamic_oauth_client_registration:
                  type:
                  - boolean
                  - 'null'
                  description: Whether dynamic OAuth client registration is enabled for the instance (RFC 7591).
                dynamic_client_allowed_scopes:
                  type:
                  - array
                  - 'null'
                  description: Administrator-selected scope ceiling for dynamically registered and automatically admitted CIMD clients. Null preserves registered client limits; defaults must be a subset. Fresh user consent is required for expansion.
                  items:
                    type: string
                default_scopes:
                  type:
                  - array
                  - 'null'
                  description: 'Default scopes assigned when a dynamically registered or first-contact CIMD client omits `scope`. Accepts built-in keys and current custom catalog keys. `advertised` does not affect eligibility. Duplicate keys, unknown keys, and `offline_access` are rejected. An empty array or null resets to Clerk-provided defaults.

                    '
                  items:
                    type: string
                oauth_jwt_access_tokens:
                  type:
                  - boolean
                  - 'null'
                  description: Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque access tokens).
                aud_claim_enabled:
                  type:
                  - boolean
                  - 'null'
                  description: Whether OAuth access tokens can include an aud claim derived from the RFC 8707 resource parameter.
                aud_claim_refresh_backfill_enabled:
                  type:
                  - boolean
                  - 'null'
                  description: Whether refresh grants without a resource can adopt the requested resource when audience claims are enabled.
                pkce_required:
                  type:
                  - boolean
                  - 'null'
                  description: Whether all new OAuth authorization-code requests must use PKCE with the S256 challenge method.
                client_id_metadata_documents_advertised:
                  type:
                  - boolean
                  - 'null'
                  description: Whether the instance advertises support for Client ID Metadata Documents in its OAuth authorization server metadata.
                client_id_metadata_documents_only_allow_pre_registered_clients:
                  type:
                  - boolean
                  - 'null'
                  description: When true, new unknown CIMD clients are rejected. Previously auto-connected and pre-registered clients remain admitted; deleting a client makes it unknown again.
                client_id_metadata_documents_block_implicitly_allowed_clients:
                  type:
                  - boolean
                  - 'null'
                  description: When true, recorded implicitly allowed CIMD clients are rejected on future client lookups. Explicitly allowed clients remain accepted. This does not revoke previously issued access tokens.
      responses:
        '200':
          $ref: '#/components/responses/InstanceOAuthApplicationSettings'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /instance/organization_settings:
    get:
      operationId: GetInstanceOrganizationSettings
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: getOrganizationSettings
      summary: Get instance organization settings
      description: Retrieves the organization settings of the instance
      tags:
      - Instance Settings
      responses:
        '200':
          $ref: '#/components/responses/OrganizationSettings'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      operationId: UpdateInstanceOrganizationSettings
      x-speakeasy-group: instanceSettings
      x-speakeasy-name-override: updateOrganizationSettings
      summary: Update instance organization settings
      description: Updates the organization settings of the instance
      tags:
      - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                enabled:
                  type:
                  - boolean
                  - 'null'
                max_allowed_memberships:
                  type:
                  - integer
                  - 'null'
                admin_delete_enabled:
                  type:
                  - boolean
                  - 'null'
                domains_enabled:
                  type:
                  - boolean
                  - 'null'
                slug_disabled:
                  type:
                  - boolean
                  - 'null'
                domains_enrollment_modes:
                  type: array
                  items:
                    type: string
                  description: 'Specify which enrollment modes to enable for your Organization Domains.

                    Supported modes are ''automatic_invitation'' & ''automatic_suggestion''.'
                creator_role_id:
                  type:
                  - string
                  - 'null'
                  description: Specify what the default organization role is for an organization creator.
                domains_default_role_id:
                  type:
                  - string
                  - 'null'
                  description: Specify what the default organization role is for the organization domains.
      responses:
        '200':
          $ref: '#/components/responses/OrganizationSettings'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
          additionalProperties: true
        clerk_trace_id:
          type: string
      required:
      - errors
    InstanceCommunication:
      type: object
      description: Per-instance SMS communication settings, including the SMS country blocklist.
      properties:
        object:
          type: string
          enum:
          - instance_communication
        blocked_country_codes:
          type: array
          description: ISO 3166-1 alpha-2 country codes that are blocked for SMS delivery on this instance. Codes that aren't recognized are silently dropped.
          items:
            type: string
      required:
      - object
      - blocked_country_codes
    Instance:
      type: object
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - instance
        id:
          type: string
        environment_type:
          type: string
          example: development
        allowed_origins:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - http://localhost:3000
          - https://some-domain
        allowed_subdomains:
          type: array
          items:
            type: string
          description: Subdomains of the instance's own domains that may originate requests, when the subdomain allowlist is enabled. Production instances only; always empty on a development instance.
          example:
          - app.example.com
          - '*.preview.example.com'
        subdomain_allowlist_enabled:
          type: boolean
          description: 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; always false on a development instance.
        workspace_id:
          type:
          - string
          - 'null'
          description: The ID of the Clerk workspace that owns the instance's application. It is null when the application has no owner.
          example: org_2abc123def456
      required:
      - object
      - id
      - environment_type
      - allowed_origins
      - allowed_subdomains
      - subdomain_allowlist_enabled
      - workspace_id
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
          additionalProperties: true
      required:
      - message
      - long_message
      - code
    InstanceRestrictions:
      type: object
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - instance_restrictions
        allowlist:
          type: boolean
        blocklist:
          type: boolean
        allowlist_blocklist_disabled_on_sign_in:
          type: boolean
        block_email_subaddresses:
          type: boolean
        block_disposable_email_domains:
          type: boolean
      required:
      - object
      - allowlist
      - blocklist
      - allowlist_blocklist_disabled_on_sign_in
      - block_email_subaddresses
      - block_disposable_email_domains
    OrganizationSettings:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - organization_settings
        enabled:
          type: boolean
        max_allowed_memberships:
          type: integer
        max_allowed_roles:
          type: integer
        max_role_sets_allowed:
          type: integer
        max_allowed_domains:
          type: integer
        max_allowed_permissions:
          deprecated: true
          description: max_allowed_permissions is now a no-op, as permissions are now unlimited
          type: integer
        creator_role:
          type: string
          description: The role key that a user will be assigned after creating an organization.
        admin_delete_enabled:
          type: boolean
          description: The default for whether an admin can delete an organization with the Frontend API.
        domains_enabled:
          type: boolean
        slug_disabled:
          type: boolean
        domains_enrollment_modes:
          type: array
          items:
            type: string
            enum:
            - manual_invitation
            - automatic_invitation
            - automatic_suggestion
        domains_default_role:
          type: string
          description: The role key that it will be used in order to create an organization invitation or suggestion.
        initial_role_set_key:
          type:
          - string
          - 'null'
          description: The role set key that it will be used to create new organizations.
      required:
      - object
      - enabled
      - max_allowed_memberships
      - max_allowed_roles
      - max_allowed_domains
      - creator_role
      - admin_delete_enabled
      - domains_enabled
      - domains_enrollment_modes
      - domains_default_role
    InstanceProtect:
      type: object
      properties:
        object:
          type: string
          enum:
          - instance_protect
        rules_enabled:
          type: boolean
          description: Whether Protect rules are enforced on this instance. False does not mean the instance is outside Protect — by default it is still evaluated in shadow, where rules are scored and recorded but never block.
        specter_enabled:
          type: boolean
          readOnly: true
          description: Whether Device Intelligence is enabled. Managed automatically or by Clerk support.
        checks_bypassed:
          type: boolean
          description: Whether the instance has opted out of the Protect prerequisite checks, asserting its setup already meets the requirements.
        checks_verified:
          type: boolean
          description: Whether the Protect system has verified the instance's prerequisite checks. Protect rules are gated on checks being verified, bypassed or exempt.
        checks_exempt:
          type: boolean
          description: Whether the instance was created into Protect and so was never subject to the prerequisite checks at all.
      required:
      - object
      - rules_enabled
      - specter_enabled
      - checks_bypassed
      - checks_verified
      - checks_exempt
    OAuthApplicationSettings:
      type: object
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - oauth_application_settings
        dynamic_oauth_client_registration:
          type: boolean
          description: Whether dynamic OAuth client registration is enabled for the instance (RFC 7591).
        dynamic_client_allowed_scopes:
          type:
          - array
          - 'null'
          description: Administrator-selected scope ceiling for dynamically registered and automatically admitted CIMD clients. Null preserves registered client limits; defaults must be a subset. Fresh user consent is required for expansion.
          items:
            type: string
        default_scopes:
          type:
          - array
          - 'null'
          description: 'Default scopes assigned when a dynamically registered or first-contact CIMD client omits `scope`. Contains built-in keys and custom catalog keys. Null means Clerk-provided defaults. `advertised` does not affect eligibility. An empty input array is stored and returned as null.

            '
          uniqueItems: true
          items:
            type: string
        oauth_jwt_access_tokens:
          type: boolean
          description: Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque access tokens).
        aud_claim_enabled:
          type: boolean
          description: Whether OAuth access tokens can include an aud claim derived from the RFC 8707 resource parameter.
        aud_claim_refresh_backfill_enabled:
          type: boolean
          description: Whether refresh grants without a resource can adopt the requested resource when audience claims are enabled.
        pkce_required:
          type: boolean
          description: Whether all new OAuth authorization-code requests must use PKCE with the S256 challenge method.
        client_id_metadata_documents_advertised:
          type: boolean
          description: Whether the instance advertises support for Client ID Metadata Documents in its OAuth authorization server metadata.
        client_id_metadata_documents_only_allow_pre_registered_clients:
          type: boolean
          description: When true, new unknown CIMD clients are rejected. Previously auto-connected and pre-registered clients remain admitted; deleting a client makes it unknown again.
        client_id_metadata_documents_block_implicitly_allowed_clients:
          type: boolean
          description: When true, recorded implicitly allowed CIMD clients are rejected on future client lookups. Explicitly allowed clients remain accepted. This does not revoke previously issued access tokens.
      required:
      - object
      - dynamic_oauth_client_registration
      - default_scopes
      - oauth_jwt_access_tokens
      - aud_claim_enabled
      - aud_claim_refresh_backfill_enabled
      - pkce_required
      - client_id_metadata_documents_advertised
      - client_id_metadata_documents_only_allow_pre_registered_clients
      - client_id_metadata_documents_block_implicitly_allowed_clients
  responses:
    InstanceOAuthApplicationSettings:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthApplicationSettings'
    InstanceProtect:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceProtect'
    OrganizationSettings:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationSettings'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    InstanceRestrictions:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceRestrictions'
    Instance:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Instance'
    InstanceCommunication:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceCommunication'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true