Clerk

Clerk Instance Settings API

Modify the settings of your instance.

GitHub OpenAPI

Operations 11

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /instance Fetch the current instance · Fetch the Current Instance #
Ask an LLM
“What are the current settings of my Clerk instance?”
“Can I read back the instance record my secret key belongs to?”
Tell an agent
Fetch my current instance.
Show the configuration of this instance.
PATCH /instance Update general instance settings · Update Instance Settings #
Ask an LLM
“How do I change the support email shown for my instance?”
“Can I turn on breached-password checks or test mode for the instance?”
Tell an agent
Set the instance support email to {support_email}.
Update the instance's allowed origins to {allowed_origins}.
PATCH /instance/restrictions Update sign-up allowlist and blocklist restrictions · Update Instance Restrictions #
Ask an LLM
“How do I restrict sign-ups to an allowlist of identifiers?”
“Can I block disposable email domains and email subaddresses on my instance?”
Tell an agent
Enable the allowlist restriction on my instance.
Block disposable email domains and email subaddresses for sign-ups.
GET /instance/protect Get the instance's protect settings · Get Instance Protect Settings #
Ask an LLM
“Are protect rules currently enabled on my instance?”
“What bot and fraud protection settings does the instance have right now?”
Tell an agent
Get the protect settings for my instance.
Show whether protect rules are turned on.
PATCH /instance/protect Update the instance's protect settings · Update Instance Protect Settings #
Ask an LLM
“How do I turn protect rules on for my instance?”
“Can I enable or disable Specter protection on the instance?”
Tell an agent
Enable protect rules on my instance.
Turn Specter protection {specter_enabled} for this instance.
GET /instance/communication Get SMS communication settings · Get Instance Communication Settings #
Ask an LLM
“Which countries are blocked from receiving SMS for my instance?”
“What SMS communication settings does my instance have?”
Tell an agent
Show my instance's SMS country blocklist.
Get the SMS communication settings for this instance.
PATCH /instance/communication Replace the SMS country blocklist · Update Instance Communication Settings #
Ask an LLM
“How do I stop sending SMS codes to certain countries?”
“What happens to unrecognized country codes in the SMS blocklist?”
Tell an agent
Block SMS delivery to countries {blocked_country_codes}.
Replace the SMS country blocklist with {blocked_country_codes}.
GET /instance/oauth_application_settings Get OAuth application settings · Get OAuth Application Settings #
Ask an LLM
“Is dynamic OAuth client registration turned on for my instance?”
“Does my instance issue JWT access tokens for OAuth applications?”
Tell an agent
Get the OAuth application settings for my instance.
Show whether dynamic client registration is enabled.
PATCH /instance/oauth_application_settings Update OAuth application settings · Update OAuth Application Settings #
Ask an LLM
“How do I allow OAuth clients to register themselves dynamically?”
“Can I switch OAuth access tokens to JWT format?”
Tell an agent
Enable dynamic OAuth client registration on my instance.
Set JWT OAuth access tokens to {oauth_jwt_access_tokens}.
GET /instance/organization_settings Get instance organization settings · Get Instance Organization Settings #
Ask an LLM
“Are organizations enabled on my instance, and what's the membership limit?”
“Which role does an organization's creator get by default?”
Tell an agent
Get the organization settings for my instance.
Show the max allowed memberships per organization.
PATCH /instance/organization_settings Update instance organization settings · Update Instance Organization Settings #
Ask an LLM
“How do I enable organizations for my instance?”
“Can I cap how many members each organization may have?”
Tell an agent
Enable organizations on my instance.
Limit organizations to {max_allowed_memberships} members each.

Documentation

📖
Documentation
https://clerk.com/docs/reference/backend-api
📖
APIReference
https://clerk.com/docs/reference/backend-api
📖
GettingStarted
https://clerk.com/docs/quickstarts/overview
📖
Authentication
https://clerk.com/docs/backend-requests/making/jwt-templates
📖
Documentation
https://clerk.com/docs
📖
Documentation
https://clerk.com/docs/webhooks/overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-instance-settings-api-openapi.yml

Other Resources

🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/rules/clerk-rules.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clerk-com:clerk-com-instance-settings-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clerk-com-instance-settings-api-openapi.yml Raw ↑ 
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: '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:
  schemas:
    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
      required:
      - object
      - id
      - environment_type
      - allowed_origins
    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
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      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
    InstanceProtect:
      type: object
      properties:
        object:
          type: string
          enum:
          - instance_protect
        rules_enabled:
          type: boolean
        specter_enabled:
          type: boolean
      required:
      - object
      - rules_enabled
      - specter_enabled
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    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
  responses:
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    InstanceProtect:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceProtect'
    OrganizationSettings:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationSettings'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Instance:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Instance'
    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'
    InstanceRestrictions:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceRestrictions'
    InstanceOAuthApplicationSettings:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthApplicationSettings'
    InstanceCommunication:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceCommunication'
  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