Clerk Enterprise Connections API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Enterprise Connections 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: Enterprise Connections
  description: 'An Enterprise Connection holds configuration data required for facilitating an enterprise SSO flow between your

    Clerk instance and an identity provider.'
  externalDocs:
    url: https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/overview
paths:
  /enterprise_connections:
    get:
      operationId: ListEnterpriseConnections
      x-speakeasy-group: enterpriseConnections
      x-speakeasy-name-override: list
      summary: List Enterprise Connections
      description: 'Returns the list of enterprise connections for the instance.

        Results can be paginated using the optional `limit` and `offset` query parameters.'
      tags:
      - Enterprise Connections
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - name: organization_id
        in: query
        required: false
        description: Filter enterprise connections by organization ID
        schema:
          type: string
      - name: active
        in: query
        required: false
        description: Filter by active status. If true, only active connections are returned. If false, only inactive connections are returned. If omitted, all connections are returned.
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/EnterpriseConnections'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateEnterpriseConnection
      x-speakeasy-group: enterpriseConnections
      x-speakeasy-name-override: create
      summary: Create an Enterprise Connection
      description: Create a new enterprise connection.
      tags:
      - Enterprise Connections
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - name
              - provider
              - domains
              properties:
                name:
                  type: string
                  description: The display name of the connection
                provider:
                  type: string
                  description: The identity provider (e.g. saml_custom, oidc_custom, oidc_github_enterprise, oidc_gitlab)
                  enum:
                  - saml_custom
                  - saml_okta
                  - saml_google
                  - saml_microsoft
                  - oidc_custom
                  - oidc_github_enterprise
                  - oidc_gitlab
                domains:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  description: Domains associated with the enterprise connection (required; at least one). Values are normalized to lowercase. Each domain must be a valid fully qualified domain name.
                organization_id:
                  type: string
                  description: Organization ID when the connection is linked to an organization
                  nullable: true
                allow_organization_account_linking:
                  type: boolean
                  description: Whether this connection supports account linking via organization membership
                  nullable: true
                active:
                  type: boolean
                  description: Whether the enterprise connection is active. When true, IdP metadata must be provided via the `saml` object.
                  nullable: true
                saml:
                  type: object
                  description: 'SAML connection-specific properties. Only applied when the enterprise connection uses SAML (e.g. provider is saml_custom).

                    Use this to set IdP configuration, attribute mapping, and other SAML-specific settings at creation time.'
                  nullable: true
                  additionalProperties: false
                  properties:
                    idp_entity_id:
                      type: string
                      description: IdP entity ID
                      nullable: true
                    idp_sso_url:
                      type: string
                      description: IdP SSO URL
                      nullable: true
                    idp_certificate:
                      type: string
                      description: IdP certificate (PEM)
                      nullable: true
                    idp_metadata_url:
                      type: string
                      description: URL to IdP metadata
                      nullable: true
                    idp_metadata:
                      type: string
                      description: Raw IdP metadata XML
                      nullable: true
                    attribute_mapping:
                      type: object
                      description: Attribute mapping for SAML attributes
                      nullable: true
                      additionalProperties: false
                      properties:
                        user_id:
                          type: string
                          nullable: true
                        email_address:
                          type: string
                          nullable: true
                        first_name:
                          type: string
                          nullable: true
                        last_name:
                          type: string
                          nullable: true
                    allow_subdomains:
                      type: boolean
                      nullable: true
                    allow_idp_initiated:
                      type: boolean
                      nullable: true
                    force_authn:
                      type: boolean
                      nullable: true
                oidc:
                  type: object
                  description: OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. provider is oidc_custom, oidc_github_enterprise, or oidc_gitlab).
                  nullable: true
                  additionalProperties: false
                  properties:
                    client_id:
                      type: string
                      description: OIDC client ID
                      nullable: true
                    client_secret:
                      type: string
                      description: OIDC client secret
                      nullable: true
                    discovery_url:
                      type: string
                      description: OIDC discovery URL
                      nullable: true
                    auth_url:
                      type: string
                      description: OIDC authorization URL
                      nullable: true
                    token_url:
                      type: string
                      description: OIDC token URL
                      nullable: true
                    user_info_url:
                      type: string
                      description: OIDC userinfo URL
                      nullable: true
                    requires_pkce:
                      type: boolean
                      description: Whether PKCE is required (must be true for public clients with no client secret)
                      nullable: true
                custom_attributes:
                  type: array
                  description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning. Requires the custom attributes feature to be enabled for the instance.
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - name
                    - key
                    properties:
                      name:
                        type: string
                        description: Display name for the custom attribute
                        minLength: 1
                      key:
                        type: string
                        description: Key used to store the attribute in the user's metadata
                        minLength: 1
                        pattern: ^[^_][A-Za-z0-9_-]*$
                      sso_path:
                        type: string
                        description: Path to extract the attribute value from SSO claims
                      scim_path:
                        type: string
                        description: GJSON path to extract the attribute value from SCIM user resources
      responses:
        '201':
          $ref: '#/components/responses/EnterpriseConnection'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /enterprise_connections/{enterprise_connection_id}:
    get:
      operationId: GetEnterpriseConnection
      x-speakeasy-group: enterpriseConnections
      x-speakeasy-name-override: get
      summary: Retrieve an Enterprise Connection
      description: Fetches the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path.
      tags:
      - Enterprise Connections
      parameters:
      - in: path
        name: enterprise_connection_id
        required: true
        schema:
          type: string
        description: The ID of the enterprise connection
      responses:
        '200':
          $ref: '#/components/responses/EnterpriseConnection'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateEnterpriseConnection
      x-speakeasy-group: enterpriseConnections
      x-speakeasy-name-override: update
      summary: Update an Enterprise Connection
      description: 'Updates the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path.

        When enabling the connection (setting `active` to true), any existing verified organization domains that match the connection''s domains (e.g. used for enrollment modes like automatic invitation) may be deleted so the connection can be enabled.'
      tags:
      - Enterprise Connections
      parameters:
      - in: path
        name: enterprise_connection_id
        required: true
        schema:
          type: string
        description: The ID of the enterprise connection to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The display name of the enterprise connection
                  nullable: true
                domains:
                  type: array
                  items:
                    type: string
                  description: 'Domains associated with the enterprise connection. Values are normalized to lowercase.

                    Empty array means ignored (no change); non-empty array means set domains to the given list (replaces existing).'
                  nullable: true
                active:
                  type: boolean
                  description: Whether the enterprise connection is active. When set to true (enabling), any existing verified organization domains for the same domain(s) will be removed so the connection can be enabled.
                  nullable: true
                sync_user_attributes:
                  type: boolean
                  description: Whether to sync user attributes on sign-in
                  nullable: true
                disable_additional_identifications:
                  type: boolean
                  description: Whether to disable additional identifications
                  nullable: true
                allow_organization_account_linking:
                  type: boolean
                  description: Whether this connection supports account linking via organization membership
                  nullable: true
                organization_id:
                  type: string
                  description: Organization ID to link to this enterprise connection. Only linking is supported; sending this field sets or changes the linked organization. There is no way to unlink an organization once linked.
                  nullable: true
                saml:
                  type: object
                  description: 'SAML connection-specific properties. Only applied when the enterprise connection uses SAML.

                    Use this to update IdP configuration, attribute mapping, and other SAML-specific settings.'
                  nullable: true
                  additionalProperties: false
                  properties:
                    name:
                      type: string
                      description: Display name of the SAML connection
                      nullable: true
                    idp_entity_id:
                      type: string
                      description: IdP entity ID
                      nullable: true
                    idp_sso_url:
                      type: string
                      description: IdP SSO URL
                      nullable: true
                    idp_certificate:
                      type: string
                      description: IdP certificate (PEM)
                      nullable: true
                    idp_metadata_url:
                      type: string
                      description: URL to IdP metadata
                      nullable: true
                    idp_metadata:
                      type: string
                      description: Raw IdP metadata XML
                      nullable: true
                    attribute_mapping:
                      type: object
                      description: Attribute mapping for SAML attributes
                      nullable: true
                      additionalProperties: false
                      properties:
                        user_id:
                          type: string
                          nullable: true
                        email_address:
                          type: string
                          nullable: true
                        first_name:
                          type: string
                          nullable: true
                        last_name:
                          type: string
                          nullable: true
                    allow_subdomains:
                      type: boolean
                      nullable: true
                    allow_idp_initiated:
                      type: boolean
                      nullable: true
                    force_authn:
                      type: boolean
                      nullable: true
                oidc:
                  type: object
                  description: OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. oidc_custom, oidc_github_enterprise, or oidc_gitlab).
                  nullable: true
                  additionalProperties: false
                  properties:
                    client_id:
                      type: string
                      description: OIDC client ID
                      nullable: true
                    client_secret:
                      type: string
                      description: OIDC client secret
                      nullable: true
                    discovery_url:
                      type: string
                      description: OIDC discovery URL
                      nullable: true
                    auth_url:
                      type: string
                      description: OIDC authorization URL
                      nullable: true
                    token_url:
                      type: string
                      description: OIDC token URL
                      nullable: true
                    user_info_url:
                      type: string
                      description: OIDC userinfo URL
                      nullable: true
                    requires_pkce:
                      type: boolean
                      description: Whether PKCE is required (must be true for public clients with no client secret)
                      nullable: true
                custom_attributes:
                  type: array
                  description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning. Requires the custom attributes feature to be enabled for the instance.
                  nullable: true
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - name
                    - key
                    properties:
                      name:
                        type: string
                        description: Display name for the custom attribute
                        minLength: 1
                      key:
                        type: string
                        description: Key used to store the attribute in the user's metadata
                        minLength: 1
                        pattern: ^[^_][A-Za-z0-9_-]*$
                      sso_path:
                        type: string
                        description: Path to extract the attribute value from SSO claims
                      scim_path:
                        type: string
                        description: GJSON path to extract the attribute value from SCIM user resources
      responses:
        '200':
          $ref: '#/components/responses/EnterpriseConnection'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteEnterpriseConnection
      x-speakeasy-group: enterpriseConnections
      x-speakeasy-name-override: delete
      summary: Delete an Enterprise Connection
      description: Deletes the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path.
      tags:
      - Enterprise Connections
      parameters:
      - in: path
        name: enterprise_connection_id
        required: true
        schema:
          type: string
        description: The ID of the enterprise connection to delete
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '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'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    EnterpriseConnection:
      description: An enterprise connection
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnterpriseConnection'
    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'
    EnterpriseConnections:
      description: A list of enterprise connections
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnterpriseConnections'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    EnterpriseConnections:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EnterpriseConnection'
        total_count:
          type: integer
          format: int64
          description: Total number of enterprise connections
      required:
      - data
      - total_count
    EnterpriseConnection:
      type: object
      required:
      - id
      - name
      - provider
      - active
      - domains
      - authenticatable
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: The enterprise connection ID
        name:
          type: string
          description: The display name of the connection
        provider:
          type: string
        logo_public_url:
          type: string
          nullable: true
        active:
          type: boolean
          description: Whether the enterprise connection is active
        domains:
          type: array
          items:
            type: string
          description: Domains associated with the enterprise connection
        organization_id:
          type: string
          description: Organization ID when the connection is linked to an organization
          nullable: true
        sync_user_attributes:
          type: boolean
          description: Controls whether to update the user's attributes on each sign-in
        disable_additional_identifications:
          type: boolean
          description: When true, users cannot add additional identifications when using this connection
        allow_organization_account_linking:
          type: boolean
          description: Whether this connection supports account linking via organization membership
        custom_attributes:
          type: array
          description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning
          items:
            type: object
            additionalProperties: false
            required:
            - name
            - key
            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
        saml_connection:
          type: object
          nullable: true
          description: Present when the enterprise connection uses SAML
          properties:
            id:
              type: string
              description: SAML connection ID
            name:
              type: string
              description: SAML connection display name
            idp_entity_id:
              type: string
              description: IdP entity ID (optional, when connection details are loaded)
              nullable: true
            idp_sso_url:
              type: string
              description: IdP SSO URL (optional, when connection details are loaded)
              nullable: true
            idp_metadata_url:
              type: string
              description: IdP metadata URL (optional, when connection details are loaded)
              nullable: true
            acs_url:
              type: string
              description: Assertion Consumer Service URL
              nullable: true
            sp_entity_id:
              type: string
              description: Service Provider entity ID
              nullable: true
            sp_metadata_url:
              type: string
              description: Service Provider metadata URL
              nullable: true
            active:
              type: boolean
              description: Whether the SAML connection is active
            allow_idp_initiated:
              type: boolean
              description: Whether IdP-initiated SSO is allowed
            allow_subdomains:
              type: boolean
              description: Whether subdomains are allowed for domain matching
            force_authn:
              type: boolean
              description: Whether to force re-authentication
        oauth_config:
          type: object
          nullable: true
          description: Present when the enterprise connection uses OIDC or EASIE
          properties:
            id:
              type: string
              description: OAuth config ID
            name:
              type: string
              description: Custom OIDC provider display name
            provider_key:
              type: string
              description: OAuth provider key (e.g. oidc_custom, oidc_ghe_*, oidc_gitlab_ent_*)
            client_id:
              type: string
              description: OAuth client ID
              nullable: true
            discovery_url:
              type: string
              description: OIDC discovery URL
              nullable: true
            auth_url:
              type: string
              description: OAuth authorization endpoint URL (present when configured or resolved from discovery)
              nullable: true
            token_url:
              type: string
              description: OAuth token endpoint URL (present when configured or resolved from discovery)
              nullable: true
            user_info_url:
              type: string
              description: OIDC userinfo endpoint URL (present when configured or resolved from discovery)
              nullable: true
            requires_pkce:
              type: boolean
              description: Whether PKCE is required for this OAuth client
            logo_public_url:
              type: string
              description: Logo URL for the provider
              nullable: true
            created_at:
              type: integer
              format: int64
              description: Unix timestamp in milliseconds when the config was created
            updated_at:
              type: integer
              format: int64
              description: Unix timestamp in milliseconds when the config was last updated
        created_at:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds when the connection was created
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds when the connection was last updated
    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
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
  parameters:
    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
    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
  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