Clerk

Clerk SAML Connections API

A SAML Connection holds configuration data required for facilitating a SAML SSO flow between your Clerk Instance (SP) and a particular SAML IdP.

GitHub OpenAPI
Business capability
Identity & Access Management BC-620.20

Operations 5

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 /saml_connections List SAML connections · Get a List of SAML Connections for an Instance #
Ask an LLM
“What SAML SSO connections are configured in my instance?”
“Can I list the SAML connections for one organization?”
Tell an agent
List all SAML connections.
Show the SAML connections of organization {organization_id}.
POST /saml_connections Create a SAML SSO connection · Create a SAML Connection #
Ask an LLM
“How do I set up SAML single sign-on for a customer's identity provider?”
“Can I configure a SAML connection from the IdP metadata URL?”
Tell an agent
Create a SAML connection {name} for provider {provider} on domain {domain}.
Set up SAML SSO {name} with provider {provider} using metadata URL {idp_metadata_url}.
GET /saml_connections/{saml_connection_id} Retrieve a SAML connection · Retrieve a SAML Connection by ID #
Ask an LLM
“How do I view the IdP settings of one SAML connection?”
“What configuration is stored on a single SAML connection?”
Tell an agent
Get SAML connection {saml_connection_id}.
Show the identity provider settings of SAML connection {saml_connection_id}.
PATCH /saml_connections/{saml_connection_id} Update a SAML connection · Update a SAML Connection #
Ask an LLM
“How do I rotate the IdP certificate on an existing SAML connection?”
“Can I deactivate a SAML connection without deleting it?”
Tell an agent
Replace the IdP certificate of SAML connection {saml_connection_id} with {idp_certificate}.
Set SAML connection {saml_connection_id} active to {active}.
DELETE /saml_connections/{saml_connection_id} Delete a SAML connection · Delete a SAML Connection #
Ask an LLM
“How do I remove a SAML SSO connection for a customer who left?”
“Can I delete a SAML connection by its ID?”
Tell an agent destructive · confirm first
Delete SAML connection {saml_connection_id}.
Remove the SSO connection {saml_connection_id}.

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-saml-connections-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-saml-connections-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-saml-connections-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Backend SAML 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.


    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: SAML Connections
  description: 'A SAML Connection holds configuration data required for facilitating a SAML SSO flow between your

    Clerk Instance (SP) and a particular SAML IdP.'
paths:
  /saml_connections:
    get:
      deprecated: true
      operationId: ListSAMLConnections
      x-speakeasy-group: samlConnections
      x-speakeasy-name-override: list
      summary: Get a List of SAML Connections for an Instance
      description: 'Returns the list of SAML Connections for an instance.

        Results can be paginated using the optional `limit` and `offset` query parameters.

        The SAML Connections are ordered by descending creation date and the most recent will be returned first.

        Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.'
      tags:
      - SAML Connections
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - name: query
        in: query
        required: false
        description: Returns SAML connections that have a name that matches the given query, via case-insensitive partial match.
        schema:
          type: string
      - name: order_by
        in: query
        required: false
        description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.

          By prepending one of those values with + or -,

          we can choose to sort in ascending (ASC) or descending (DESC) order.'
        schema:
          type: string
      - name: organization_id
        in: query
        schema:
          type: array
          items:
            type: string
        description: 'Returns SAML connections that have an associated organization ID to the

          given organizations.

          For each organization ID, the `+` and `-` can be

          prepended to the ID, which denote whether the

          respective organization should be included or

          excluded from the result set.

          Accepts up to 100 organization IDs.'
      responses:
        '200':
          $ref: '#/components/responses/SAMLConnections'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      deprecated: true
      operationId: CreateSAMLConnection
      x-speakeasy-group: samlConnections
      x-speakeasy-name-override: create
      summary: Create a SAML Connection
      description: 'Create a new SAML Connection.

        Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.'
      tags:
      - SAML Connections
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The name to use as a label for this SAML Connection
                domain:
                  type: string
                  deprecated: true
                  description: The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection.
                domains:
                  type: array
                  items:
                    type: string
                  description: The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection.
                provider:
                  type: string
                  description: The IdP provider of the connection.
                  enum:
                  - saml_custom
                  - saml_okta
                  - saml_google
                  - saml_microsoft
                idp_entity_id:
                  type:
                  - string
                  - 'null'
                  description: The Entity ID as provided by the IdP
                idp_sso_url:
                  type:
                  - string
                  - 'null'
                  description: The Single-Sign On URL as provided by the IdP
                idp_certificate:
                  type:
                  - string
                  - 'null'
                  description: The X.509 certificate as provided by the IdP
                idp_metadata_url:
                  type:
                  - string
                  - 'null'
                  description: The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties
                idp_metadata:
                  type:
                  - string
                  - 'null'
                  description: The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties
                organization_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the organization to which users of this SAML Connection will be added
                attribute_mapping:
                  type:
                  - object
                  - 'null'
                  description: Define the attribute name mapping between Identity Provider and Clerk's user properties
                  additionalProperties: false
                  properties:
                    user_id:
                      type: string
                    email_address:
                      type: string
                    first_name:
                      type: string
                    last_name:
                      type: string
                force_authn:
                  type: boolean
                  description: Enable or deactivate ForceAuthn
              required:
              - name
              - provider
              anyOf:
              - required:
                - domain
              - required:
                - domains
      responses:
        '200':
          $ref: '#/components/responses/SAMLConnection'
        '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'
  /saml_connections/{saml_connection_id}:
    get:
      deprecated: true
      operationId: GetSAMLConnection
      x-speakeasy-group: samlConnections
      x-speakeasy-name-override: get
      summary: Retrieve a SAML Connection by ID
      description: 'Fetches the SAML Connection whose ID matches the provided `saml_connection_id` in the path.

        Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.'
      tags:
      - SAML Connections
      parameters:
      - in: path
        name: saml_connection_id
        required: true
        schema:
          type: string
        description: The ID of the SAML Connection
      responses:
        '200':
          $ref: '#/components/responses/SAMLConnection'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      deprecated: true
      operationId: UpdateSAMLConnection
      x-speakeasy-group: samlConnections
      x-speakeasy-name-override: update
      summary: Update a SAML Connection
      description: 'Updates the SAML Connection whose ID matches the provided `id` in the path.

        Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.'
      tags:
      - SAML Connections
      parameters:
      - in: path
        name: saml_connection_id
        required: true
        schema:
          type: string
        description: The ID of the SAML Connection to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  description: The name of the new SAML Connection
                domain:
                  type:
                  - string
                  - 'null'
                  description: The domain to use for the new SAML Connection
                  deprecated: true
                domains:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: A list of the domains on use for the SAML connection
                idp_entity_id:
                  type:
                  - string
                  - 'null'
                  description: The Entity ID as provided by the IdP
                idp_sso_url:
                  type:
                  - string
                  - 'null'
                  description: The SSO URL as provided by the IdP
                idp_certificate:
                  type:
                  - string
                  - 'null'
                  description: The x509 certificated as provided by the IdP
                idp_metadata_url:
                  type:
                  - string
                  - 'null'
                  description: The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them
                idp_metadata:
                  type:
                  - string
                  - 'null'
                  description: The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties
                organization_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the organization to which users of this SAML Connection will be added
                attribute_mapping:
                  type:
                  - object
                  - 'null'
                  description: Define the attribute name mapping between Identity Provider and Clerk's user properties
                  additionalProperties: false
                  properties:
                    user_id:
                      type: string
                    email_address:
                      type: string
                    first_name:
                      type: string
                    last_name:
                      type: string
                active:
                  type:
                  - boolean
                  - 'null'
                  description: Activate or de-activate the SAML Connection
                sync_user_attributes:
                  type:
                  - boolean
                  - 'null'
                  description: Controls whether to update the user's attributes in each sign-in
                allow_subdomains:
                  type:
                  - boolean
                  - 'null'
                  description: Allow users with an email address subdomain to use this connection in order to authenticate
                allow_idp_initiated:
                  type:
                  - boolean
                  - 'null'
                  description: Enable or deactivate IdP-initiated flows
                disable_additional_identifications:
                  type:
                  - boolean
                  - 'null'
                  description: Enable or deactivate additional identifications
                allow_organization_account_linking:
                  type:
                  - boolean
                  - 'null'
                  description: Whether this connection supports account linking via organization membership
                force_authn:
                  type: boolean
                  description: Enable or deactivate ForceAuthn
                consent_verified_domains_deletion:
                  type:
                  - boolean
                  - 'null'
                  description: When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.
      responses:
        '200':
          $ref: '#/components/responses/SAMLConnection'
        '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'
    delete:
      deprecated: true
      operationId: DeleteSAMLConnection
      x-speakeasy-group: samlConnections
      x-speakeasy-name-override: delete
      summary: Delete a SAML Connection
      description: 'Deletes the SAML Connection whose ID matches the provided `id` in the path.

        Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.'
      tags:
      - SAML Connections
      parameters:
      - in: path
        name: saml_connection_id
        required: true
        schema:
          type: string
        description: The ID of the SAML 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:
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    SAMLConnections:
      description: A list of SAML Connections
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SAMLConnections'
    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'
    SAMLConnection:
      description: A SAML Connection
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SAMLConnection'
  schemas:
    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
    SAMLConnections:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SAMLConnection'
        total_count:
          type: integer
          format: int64
          description: 'Total number of SAML Connections

            '
      required:
      - data
      - total_count
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    SAMLConnectionAttributeMapping:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
        email_address:
          type: string
        first_name:
          type: string
        last_name:
          type: string
      required:
      - user_id
      - email_address
      - first_name
      - last_name
    SAMLConnection:
      type: object
      properties:
        object:
          type: string
          enum:
          - saml_connection
        id:
          type: string
        name:
          type: string
        domain:
          type: string
          deprecated: true
        domains:
          type: array
          items:
            type: string
        idp_entity_id:
          type:
          - string
          - 'null'
        idp_sso_url:
          type:
          - string
          - 'null'
        idp_certificate:
          type:
          - string
          - 'null'
        idp_metadata_url:
          type:
          - string
          - 'null'
        idp_metadata:
          type:
          - string
          - 'null'
        acs_url:
          type: string
        sp_entity_id:
          type: string
        sp_metadata_url:
          type: string
        organization_id:
          type:
          - string
          - 'null'
        attribute_mapping:
          $ref: '#/components/schemas/SAMLConnectionAttributeMapping'
        active:
          type: boolean
        provider:
          type: string
        user_count:
          type: integer
        sync_user_attributes:
          type: boolean
        allow_subdomains:
          type: boolean
        allow_idp_initiated:
          type: boolean
        disable_additional_identifications:
          type: boolean
        allow_organization_account_linking:
          type: boolean
        force_authn:
          type: boolean
          description: Enable or deactivate ForceAuthn
        enterprise_connection_id:
          type:
          - string
          - 'null'
        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
      - idp_entity_id
      - idp_sso_url
      - idp_certificate
      - acs_url
      - sp_entity_id
      - sp_metadata_url
      - active
      - provider
      - user_count
      - sync_user_attributes
      - allow_subdomains
      - allow_idp_initiated
      - disable_additional_identifications
      - allow_organization_account_linking
      - authenticatable
      - force_authn
      - created_at
      - updated_at
      anyOf:
      - required:
        - domain
      - required:
        - domains
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
  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