Clerk docs

SAML Connections

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

Get a list of SAML Connections for an instance

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.

SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

Responses
200

A list of SAML Connections

402

Payment required

403

Authorization invalid

422

Invalid request parameters

get/saml_connections
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Create a SAML Connection

Create a new SAML Connection.

SecuritybearerAuth
Request
Request Body schema: application/json
name
required
string

The name to use as a label for this SAML Connection

domain
required
string

The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection.

provider
required
string

The IdP provider of the connection.

Enum: "saml_custom" "saml_okta" "saml_google" "saml_microsoft"
idp_entity_id
string or null

The Entity ID as provided by the IdP

idp_sso_url
string or null

The Single-Sign On URL as provided by the IdP

idp_certificate
string or null

The X.509 certificate as provided by the IdP

idp_metadata_url
string or null

The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties

idp_metadata
string or null

The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties

object or null

Define the attribute name mapping between Identity Provider and Clerk's user properties

Responses
200

A SAML Connection

402

Payment required

403

Authorization invalid

422

Invalid request parameters

post/saml_connections
Request samples
application/json
{
  • "name": "string",
  • "domain": "string",
  • "provider": "saml_custom",
  • "idp_entity_id": "string",
  • "idp_sso_url": "string",
  • "idp_certificate": "string",
  • "idp_metadata_url": "string",
  • "idp_metadata": "string",
  • "attribute_mapping": {
    }
}
Response samples
application/json
{
  • "object": "saml_connection",
  • "id": "string",
  • "name": "string",
  • "domain": "string",
  • "idp_entity_id": "string",
  • "idp_sso_url": "string",
  • "idp_certificate": "string",
  • "idp_metadata_url": "string",
  • "idp_metadata": "string",
  • "acs_url": "string",
  • "sp_entity_id": "string",
  • "sp_metadata_url": "string",
  • "attribute_mapping": {
    },
  • "active": true,
  • "provider": "string",
  • "user_count": 0,
  • "sync_user_attributes": true,
  • "allow_subdomains": true,
  • "allow_idp_initiated": true,
  • "disable_additional_identifications": true,
  • "created_at": 0,
  • "updated_at": 0
}

Retrieve a SAML Connection by ID

Fetches the SAML Connection whose ID matches the provided saml_connection_id in the path.

SecuritybearerAuth
Request
path Parameters
saml_connection_id
required
string

The ID of the SAML Connection

Responses
200

A SAML Connection

402

Payment required

403

Authorization invalid

404

Resource not found

get/saml_connections/{saml_connection_id}
Response samples
application/json
{
  • "object": "saml_connection",
  • "id": "string",
  • "name": "string",
  • "domain": "string",
  • "idp_entity_id": "string",
  • "idp_sso_url": "string",
  • "idp_certificate": "string",
  • "idp_metadata_url": "string",
  • "idp_metadata": "string",
  • "acs_url": "string",
  • "sp_entity_id": "string",
  • "sp_metadata_url": "string",
  • "attribute_mapping": {
    },
  • "active": true,
  • "provider": "string",
  • "user_count": 0,
  • "sync_user_attributes": true,
  • "allow_subdomains": true,
  • "allow_idp_initiated": true,
  • "disable_additional_identifications": true,
  • "created_at": 0,
  • "updated_at": 0
}

Update a SAML Connection

Updates the SAML Connection whose ID matches the provided id in the path.

SecuritybearerAuth
Request
path Parameters
saml_connection_id
required
string

The ID of the SAML Connection to update

Request Body schema: application/json
required
name
string or null

The name of the new SAML Connection

domain
string or null

The domain to use for the new SAML Connection

idp_entity_id
string or null

The entity id as provided by the IdP

idp_sso_url
string or null

The SSO url as provided by the IdP

idp_certificate
string or null

The x509 certificated as provided by the IdP

idp_metadata_url
string or null

The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them

idp_metadata
string or null

The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties

object or null

Define the atrtibute name mapping between Identity Provider and Clerk's user properties

active
boolean or null

Activate or de-activate the SAML Connection

sync_user_attributes
boolean or null

Controls whether to update the user's attributes in each sign-in

allow_subdomains
boolean or null

Allow users with an email address subdomain to use this connection in order to authenticate

allow_idp_initiated
boolean or null

Enable or deactivate IdP-initiated flows

disable_additional_identifications
boolean or null

Enable or deactivate additional identifications

Responses
200

A SAML Connection

402

Payment required

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

patch/saml_connections/{saml_connection_id}
Request samples
application/json
{
  • "name": "string",
  • "domain": "string",
  • "idp_entity_id": "string",
  • "idp_sso_url": "string",
  • "idp_certificate": "string",
  • "idp_metadata_url": "string",
  • "idp_metadata": "string",
  • "attribute_mapping": {
    },
  • "active": true,
  • "sync_user_attributes": true,
  • "allow_subdomains": true,
  • "allow_idp_initiated": true,
  • "disable_additional_identifications": true
}
Response samples
application/json
{
  • "object": "saml_connection",
  • "id": "string",
  • "name": "string",
  • "domain": "string",
  • "idp_entity_id": "string",
  • "idp_sso_url": "string",
  • "idp_certificate": "string",
  • "idp_metadata_url": "string",
  • "idp_metadata": "string",
  • "acs_url": "string",
  • "sp_entity_id": "string",
  • "sp_metadata_url": "string",
  • "attribute_mapping": {
    },
  • "active": true,
  • "provider": "string",
  • "user_count": 0,
  • "sync_user_attributes": true,
  • "allow_subdomains": true,
  • "allow_idp_initiated": true,
  • "disable_additional_identifications": true,
  • "created_at": 0,
  • "updated_at": 0
}

Delete a SAML Connection

Deletes the SAML Connection whose ID matches the provided id in the path.

SecuritybearerAuth
Request
path Parameters
saml_connection_id
required
string

The ID of the SAML Connection to delete

Responses
200

Deleted Object

402

Payment required

403

Authorization invalid

404

Resource not found

delete/saml_connections/{saml_connection_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}
➔ Next to Sessions