Clerk Config API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Config 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: Config
  description: Operations for managing instance configuration. The config API provides a unified interface for reading and updating instance settings, including authentication methods, SSO connections, and other instance-level configuration options.
paths:
  /platform/applications/{applicationID}/instances/{envOrInsID}/config:
    get:
      operationId: PlatformGetConfig
      x-speakeasy-group: platform
      x-speakeasy-name-override: getConfig
      tags:
      - Config
      summary: Get Instance Config
      description: 'Get the configuration for an application instance.


        The `envOrInsID` parameter can be either an environment type (e.g., "development", "production")

        or an instance ID.


        Optionally filter to specific config keys using the `keys` query parameter.


        Requires the `applications:manage` scope.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: envOrInsID
        in: path
        description: 'Environment type (e.g., "development", "production") or instance ID.

          '
        required: true
        schema:
          type: string
      - name: keys
        in: query
        description: Config keys to retrieve. If not specified, all keys are returned.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Instance config retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformConfigResponse'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: PlatformPatchConfig
      x-speakeasy-group: platform
      x-speakeasy-name-override: patchConfig
      tags:
      - Config
      summary: Update Instance Config
      description: 'Update the configuration for an application instance.


        The `envOrInsID` parameter can be either an environment type (e.g., "development", "production")

        or an instance ID.


        Use the `dry_run` query parameter to preview changes without applying them.

        Use the `destructive` query parameter to allow clearing config keys by setting them to null.

        Use the `If-Match` header to provide optimistic concurrency control via config version.


        Requires the `applications:manage` scope.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: envOrInsID
        in: path
        description: 'Environment type (e.g., "development", "production") or instance ID.

          '
        required: true
        schema:
          type: string
      - name: dry_run
        in: query
        description: If true, preview the changes without applying them.
        required: false
        schema:
          type: boolean
          default: false
      - name: destructive
        in: query
        description: If true, allow clearing config keys by setting them to null.
        required: false
        schema:
          type: boolean
          default: false
      - name: keys
        in: query
        description: Config keys to return in the response. If not specified, only updated keys are returned.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: If-Match
        in: header
        description: Config version for optimistic concurrency control.
        required: false
        schema:
          type: string
      requestBody:
        description: Config updates to apply.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformConfigPatchRequest'
      responses:
        '200':
          description: Instance config updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformConfigPatchResponse'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      operationId: PlatformPutConfig
      x-speakeasy-group: platform
      x-speakeasy-name-override: putConfig
      tags:
      - Config
      summary: Replace Instance Config
      description: 'Replace the full configuration for an application instance.


        Unlike PATCH, PUT requires all config keys to be included in the request body.

        If any keys are missing, a 400 error is returned listing the missing keys.


        The `envOrInsID` parameter can be either an environment type (e.g., "development", "production")

        or an instance ID.


        Use the `dry_run` query parameter to preview changes without applying them.

        Use the `destructive` query parameter to allow clearing config keys by setting them to null.

        Use the `If-Match` header to provide optimistic concurrency control via config version.


        Requires the `applications:manage` scope.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: envOrInsID
        in: path
        description: 'Environment type (e.g., "development", "production") or instance ID.

          '
        required: true
        schema:
          type: string
      - name: dry_run
        in: query
        description: If true, preview the changes without applying them.
        required: false
        schema:
          type: boolean
          default: false
      - name: destructive
        in: query
        description: If true, allow clearing config keys by setting them to null.
        required: false
        schema:
          type: boolean
          default: false
      - name: If-Match
        in: header
        description: Config version for optimistic concurrency control.
        required: false
        schema:
          type: string
      requestBody:
        description: Complete config to apply. All config keys must be included.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformConfigPatchRequest'
      responses:
        '200':
          description: Instance config replaced successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformConfigPatchResponse'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /platform/applications/{applicationID}/instances/{envOrInsID}/config/schema:
    get:
      operationId: PlatformGetConfigSchema
      x-speakeasy-group: platform
      x-speakeasy-name-override: getConfigSchema
      tags:
      - Config
      summary: Get Instance Config Schema
      description: 'Get the JSON Schema for the instance configuration.


        The `envOrInsID` parameter can be either an environment type (e.g., "development", "production")

        or an instance ID.


        Optionally filter to specific config keys using the `keys` query parameter.


        Requires the `applications:manage` scope.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: envOrInsID
        in: path
        description: 'Environment type (e.g., "development", "production") or instance ID.

          '
        required: true
        schema:
          type: string
      - name: keys
        in: query
        description: Config keys to retrieve schema for. If not specified, all keys are returned.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Instance config schema retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformConfigSchemaResponse'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
components:
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    PlatformConfigResponse:
      type: object
      description: Instance configuration response containing key-value pairs and metadata.
      properties:
        config_version:
          type: string
          description: Configuration version for optimistic concurrency control.
      additionalProperties: true
    PlatformConfigPatchResponse:
      type: object
      description: Configuration patch response containing the result of the operation.
      properties:
        config_version:
          type: string
          description: Updated configuration version.
        dry_run:
          type: boolean
          description: Whether this was a dry run (changes were not applied).
        before:
          type: object
          description: Configuration state before the patch was applied.
          additionalProperties: true
        after:
          type: object
          description: Configuration state after the patch was applied.
          additionalProperties: true
      additionalProperties: true
    PlatformConfigSchemaResponse:
      type: object
      description: JSON Schema describing the available configuration options.
      properties:
        $schema:
          type: string
          description: JSON Schema version.
        $id:
          type: string
          description: Schema identifier.
        type:
          type: string
        properties:
          type: object
          description: Schema definitions for each configuration key.
          additionalProperties: true
      additionalProperties: true
    PlatformConfigPatchRequest:
      type: object
      description: Configuration updates to apply. Keys should match config key names.
      additionalProperties: true
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
  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