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](https://clerk.com/docs/versioning/available-versions).


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  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
                  items:
                    type: string
                  description: 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_uuid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost.
                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).
      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'
                specter_enabled:
                  type:
                  - boolean
                  - 'null'
      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).
                oauth_jwt_access_tokens:
                  type:
                  - boolean
                  - 'null'
                  description: Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque 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'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  responses:
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    InstanceProtect:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceProtect'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Instance:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Instance'
    InstanceOAuthApplicationSettings:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthApplicationSettings'
    OrganizationSettings:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationSettings'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    InstanceCommunication:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceCommunication'
    InstanceRestrictions:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceRestrictions'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    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
    InstanceProtect:
      type: object
      properties:
        object:
          type: string
          enum:
          - instance_protect
        rules_enabled:
          type: boolean
        specter_enabled:
          type: boolean
      required:
      - object
      - rules_enabled
      - specter_enabled
    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).
        oauth_jwt_access_tokens:
          type: boolean
          description: Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque access tokens).
      required:
      - object
      - dynamic_oauth_client_registration
      - oauth_jwt_access_tokens
    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
    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
      required:
      - object
      - id
      - environment_type
      - allowed_origins
    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
  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