Clerk SCIM Directories API

openapi: 3.2.0
info:
  title: Clerk Backend SCIM Directories 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: SCIM Directories
paths:
  /scim_directories:
    get:
      operationId: ListSCIMDirectories
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: list
      tags:
      - SCIM Directories
      summary: List all directories
      description: Returns a list of all directories for the instance.
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/SCIMDirectory.List'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
    post:
      operationId: CreateSCIMDirectory
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: create
      tags:
      - SCIM Directories
      summary: Create a directory
      description: Create a new directory for the instance.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enterprise_connection_id:
                  type: string
                  description: The ID of the enterprise connection to associate with this directory.
                name:
                  type: string
                  description: A human-friendly name for the directory.
                provider:
                  type: string
                  description: The identity provider for this directory.
                group_role_mappings:
                  type: array
                  description: Optional SCIM group to organization role mappings to create with the directory.
                  items:
                    type: object
                    properties:
                      scim_group_id:
                        type: string
                        description: The SCIM group ID from the identity provider.
                      scim_group_display_name:
                        type: string
                        maxLength: 255
                        description: Optional display name for the SCIM group.
                      role_id:
                        type: string
                        description: The organization role ID to assign to members of the SCIM group.
                      precedence:
                        type: integer
                        minimum: 1
                        description: The precedence for this mapping. If omitted, precedence is assigned by array order.
                    required:
                    - scim_group_id
                    - role_id
              required:
              - enterprise_connection_id
              - provider
      responses:
        '200':
          $ref: '#/components/responses/SCIMDirectory'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /scim_directories/{scim_directory_id}:
    get:
      operationId: GetSCIMDirectory
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: get
      tags:
      - SCIM Directories
      summary: Retrieve a directory
      description: Returns the details of a directory.
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SCIMDirectory'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateSCIMDirectory
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: update
      tags:
      - SCIM Directories
      summary: Update a directory
      description: Updates a directory.
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A human-friendly name for the directory.
                enabled:
                  type: boolean
                  description: Whether the directory is enabled.
                provider:
                  type: string
                  description: The identity provider for this directory.
                attribute_mapping:
                  type: object
                  additionalProperties:
                    type:
                    - string
                    - 'null'
                  description: 'Attribute-to-SCIM-path entries to merge into the directory''s attribute mapping.

                    Set a key to `null` to remove it from the mapping.'
                group_role_mapping_enabled:
                  type: boolean
                  description: Whether group-to-role mapping is enabled for this directory.
      responses:
        '200':
          $ref: '#/components/responses/SCIMDirectory'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteSCIMDirectory
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: delete
      tags:
      - SCIM Directories
      summary: Delete a directory
      description: 'Deletes a directory and stops provisioning for it. SCIM requests authenticated

        with the directory''s API key are rejected afterwards.'
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory to delete
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /scim_directories/{scim_directory_id}/rotate_api_key:
    post:
      operationId: RotateSCIMDirectoryAPIKey
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: rotateApiKey
      tags:
      - SCIM Directories
      summary: Rotate a directory's API key
      description: 'Generates a new API key for the directory and returns it in the `api_key` field.

        This is the only way to obtain the key after creation, so make sure to update it in

        your identity provider. The previous key remains valid for a short grace period before

        it expires.'
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory whose API key to rotate
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SCIMDirectory'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /scim_directories/{scim_directory_id}/group_role_mappings:
    get:
      operationId: ListSCIMGroupRoleMappings
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: listGroupRoleMappings
      tags:
      - SCIM Directories
      summary: List SCIM group role mappings
      description: Returns the list of SCIM group to organization role mappings for a directory, ordered by precedence.
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SCIMGroupRoleMapping.List'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    post:
      operationId: CreateSCIMGroupRoleMapping
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: createGroupRoleMapping
      tags:
      - SCIM Directories
      summary: Create a SCIM group role mapping
      description: 'Creates a new SCIM group to organization role mapping for a directory.

        Mappings can be created while group role mapping is disabled on the

        directory, but they only take effect once it is enabled.'
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scim_group_id:
                  type: string
                  description: The SCIM group ID from the identity provider.
                role_id:
                  type: string
                  description: The ID of the organization role to assign to members of the SCIM group.
                precedence:
                  type: integer
                  minimum: 1
                  description: 'The precedence for this mapping. Lower values take priority when a user belongs

                    to multiple mapped groups. If omitted, the mapping is appended with the

                    next-highest precedence.'
              required:
              - scim_group_id
              - role_id
      responses:
        '200':
          $ref: '#/components/responses/SCIMGroupRoleMapping'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      operationId: ReplaceSCIMGroupRoleMappings
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: replaceGroupRoleMappings
      tags:
      - SCIM Directories
      summary: Replace SCIM group role mappings
      description: 'Replaces the entire set of SCIM group role mappings for a directory. The position of

        each item in the `mappings` array determines its precedence (the first item gets

        precedence 1). Passing an empty array removes all mappings. Mappings can be replaced

        while group role mapping is disabled on the directory, but they only take effect once

        it is enabled.'
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mappings:
                  type: array
                  description: The desired set of mappings. Array order sets precedence (1-indexed). An empty array clears all mappings.
                  items:
                    type: object
                    properties:
                      scim_group_id:
                        type: string
                        description: The SCIM group ID from the identity provider.
                      role_id:
                        type: string
                        description: The ID of the organization role to assign to members of the SCIM group.
                    required:
                    - scim_group_id
                    - role_id
              required:
              - mappings
      responses:
        '200':
          $ref: '#/components/responses/SCIMGroupRoleMapping.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /scim_directories/{scim_directory_id}/group_role_mappings/{mapping_id}:
    delete:
      operationId: DeleteSCIMGroupRoleMapping
      x-speakeasy-group: scimDirectories
      x-speakeasy-name-override: deleteGroupRoleMapping
      tags:
      - SCIM Directories
      summary: Delete a SCIM group role mapping
      description: 'Deletes a single SCIM group role mapping. Mappings can be deleted while group role

        mapping is disabled on the directory, but the change only takes effect once it is

        enabled.'
      parameters:
      - name: scim_directory_id
        in: path
        description: The ID of the directory.
        required: true
        schema:
          type: string
      - name: mapping_id
        in: path
        description: The ID of the SCIM group role mapping to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SCIMGroupRoleMapping.Deleted'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
components:
  schemas:
    SCIMGroupRoleMappings:
      type: array
      items:
        $ref: '#/components/schemas/SCIMGroupRoleMapping'
    SCIMDirectory:
      type: object
      description: A directory configuration for provisioning users via SCIM protocol.
      properties:
        object:
          type: string
          description: String representing the object's type. Always "scim_directory".
          enum:
          - scim_directory
        id:
          type: string
          description: Unique identifier for the directory.
        name:
          type: string
          description: A human-friendly name for the directory.
        enterprise_connection_id:
          type:
          - string
          - 'null'
          description: The ID of the associated enterprise connection.
        endpoint_url:
          type: string
          description: The SCIM endpoint URL for this directory.
        provider:
          type: string
          description: The identity provider for this directory.
        enabled:
          type: boolean
          description: Whether the directory is enabled.
        group_role_mapping_enabled:
          type: boolean
          description: Whether group-to-role mapping is enabled for this directory.
        attribute_mapping:
          type: object
          additionalProperties:
            type: string
          description: Mapping of user attributes to the SCIM attribute paths they are extracted from.
        custom_attributes:
          type: array
          description: Custom attributes to map from the IdP to the user's profile via SCIM provisioning. Requires the custom attributes feature to be enabled for the instance.
          items:
            type: object
            properties:
              name:
                type: string
                description: Display name for the custom attribute
              key:
                type: string
                description: Key used to store the attribute in the user's public/private/unsafe metadata
              sso_path:
                type: string
                description: Path to extract the attribute value from SSO claims (SAML assertions or OIDC claims)
              scim_path:
                type: string
                description: GJSON path to extract the attribute value from SCIM user resources
              directory_path:
                type: string
                description: GJSON path to extract the attribute value from directory sync user resources. Same value as `scim_path`.
              multi_valued:
                type: boolean
                description: When true, the attribute supports multiple values; values from the IdP are written to public_metadata as an array. Defaults to false.
        api_key:
          type:
          - string
          - 'null'
          description: The API key for authenticating SCIM requests. Only returned when the directory is created or the key is rotated.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when the directory was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when the directory was last updated.
      required:
      - object
      - id
      - name
      - endpoint_url
      - provider
      - enabled
      - group_role_mapping_enabled
      - attribute_mapping
      - created_at
      - updated_at
    DeletedObject:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
        id:
          type: string
        slug:
          type: string
        deleted:
          type: boolean
        external_id:
          type: string
      required:
      - object
      - deleted
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
          additionalProperties: true
      required:
      - message
      - long_message
      - code
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
          additionalProperties: true
        clerk_trace_id:
          type: string
      required:
      - errors
    Permission:
      type: object
      properties:
        object:
          type: string
          enum:
          - permission
        id:
          type: string
        name:
          type: string
        key:
          type: string
        description:
          type: string
        type:
          type: string
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
      required:
      - object
      - id
      - name
      - key
      - description
      - type
      - created_at
      - updated_at
    Role:
      type: object
      properties:
        object:
          type: string
          enum:
          - role
        id:
          type: string
        name:
          type: string
        key:
          type: string
        description:
          type:
          - string
          - 'null'
        is_creator_eligible:
          type: boolean
          description: Whether this role is eligible to be an organization creator role
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
      additionalProperties: false
      required:
      - object
      - id
      - name
      - key
      - description
      - is_creator_eligible
      - permissions
      - created_at
      - updated_at
    SCIMDirectories:
      type: array
      items:
        $ref: '#/components/schemas/SCIMDirectory'
    SCIMGroupRoleMapping:
      type: object
      description: A mapping from a SCIM group to an organization role. Members of the group are assigned the role; the lowest-precedence match wins when a user belongs to multiple mapped groups.
      properties:
        object:
          type: string
          description: String representing the object's type. Always "scim_group_role_mapping".
          enum:
          - scim_group_role_mapping
        id:
          type: string
          description: Unique identifier for the SCIM group role mapping.
        scim_directory_id:
          type: string
          description: The ID of the directory this mapping belongs to.
        directory_id:
          type: string
          description: The ID of the directory this mapping belongs to. Same value as `scim_directory_id`.
        scim_group_id:
          type: string
          description: The SCIM group ID from the identity provider.
        directory_group_id:
          type: string
          description: The group ID from the identity provider. Same value as `scim_group_id`.
        scim_group_display_name:
          type: string
          description: The display name of the SCIM group, as reported by the identity provider.
        directory_group_display_name:
          type: string
          description: The display name of the group, as reported by the identity provider. Same value as `scim_group_display_name`.
        role:
          $ref: '#/components/schemas/Role'
        precedence:
          type: integer
          description: Mapping precedence, starting at 1. Lower values take priority when a user belongs to multiple mapped groups.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of when the mapping was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of when the mapping was last updated.
      required:
      - object
      - id
      - scim_directory_id
      - directory_id
      - scim_group_id
      - directory_group_id
      - scim_group_display_name
      - directory_group_display_name
      - precedence
      - created_at
      - updated_at
  responses:
    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'
    SCIMDirectory.List:
      description: A list of directories
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/SCIMDirectories'
              total_count:
                type: integer
                description: Total number of directories.
            required:
            - data
            - total_count
    SCIMGroupRoleMapping.List:
      description: A list of SCIM group role mappings, ordered by precedence.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/SCIMGroupRoleMappings'
              total_count:
                type: integer
                format: int64
                description: Total number of SCIM group role mappings in the directory.
            required:
            - data
            - total_count
    SCIMDirectory:
      description: A directory
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SCIMDirectory'
    SCIMGroupRoleMapping:
      description: A SCIM group role mapping
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SCIMGroupRoleMapping'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    SCIMGroupRoleMapping.Deleted:
      description: A SCIM group role mapping was deleted.
      content:
        application/json:
          schema:
            type: object
            properties:
              object:
                type: string
                enum:
                - scim_group_role_mapping
                description: String representing the object's type.
              id:
                type: string
                description: The ID of the deleted SCIM group role mapping.
              deleted:
                type: boolean
                enum:
                - true
                description: Whether the SCIM group role mapping was successfully deleted.
            required:
            - object
            - id
            - deleted
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  parameters:
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
  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