---
title: "Create a SAML Connection"
method: POST
path: "/saml_connections"
tags: ["SAML Connections"]
deprecated: true
---

# Create a SAML Connection

`POST /saml_connections`

> **Deprecated.**

Create a new SAML Connection.
Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.

## Request body

- union
  - object
    - `name` string, required — The name to use as a label for this SAML Connection
    - `domain` string, required — The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection.
    - `domains` string[] — The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection.
    - `provider` 'saml_custom' | 'saml_okta' | 'saml_google' | 'saml_microsoft', required — The IdP provider of the connection.
    - `idp_entity_id` string, nullable — The Entity ID as provided by the IdP
    - `idp_sso_url` string, nullable — The Single-Sign On URL as provided by the IdP
    - `idp_certificate` string, nullable — The X.509 certificate as provided by the IdP
    - `idp_metadata_url` string, nullable — The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties
    - `idp_metadata` string, nullable — The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties
    - `organization_id` string, nullable — The ID of the organization to which users of this SAML Connection will be added
    - `attribute_mapping` object, nullable — Define the attribute name mapping between Identity Provider and Clerk's user properties
      - `user_id` string
      - `email_address` string
      - `first_name` string
      - `last_name` string
    - `force_authn` boolean — Enable or deactivate ForceAuthn
    - `login_hint` object, nullable — Configuration for the login_hint sent to the IdP on SSO sign-in
      - `mode` 'email_address' | 'custom_attribute' | 'off', required — Controls the login_hint sent to the IdP on SSO sign-in
      - `source` string — The user public_metadata key whose value is sent as the login_hint when mode is custom_attribute
  - object
    - `name` string, required — The name to use as a label for this SAML Connection
    - `domain` string — The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection.
    - `domains` string[], required — The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection.
    - `provider` 'saml_custom' | 'saml_okta' | 'saml_google' | 'saml_microsoft', required — The IdP provider of the connection.
    - `idp_entity_id` string, nullable — The Entity ID as provided by the IdP
    - `idp_sso_url` string, nullable — The Single-Sign On URL as provided by the IdP
    - `idp_certificate` string, nullable — The X.509 certificate as provided by the IdP
    - `idp_metadata_url` string, nullable — The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties
    - `idp_metadata` string, nullable — The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties
    - `organization_id` string, nullable — The ID of the organization to which users of this SAML Connection will be added
    - `attribute_mapping` object, nullable — Define the attribute name mapping between Identity Provider and Clerk's user properties
      - `user_id` string
      - `email_address` string
      - `first_name` string
      - `last_name` string
    - `force_authn` boolean — Enable or deactivate ForceAuthn
    - `login_hint` object, nullable — Configuration for the login_hint sent to the IdP on SSO sign-in
      - `mode` 'email_address' | 'custom_attribute' | 'off', required — Controls the login_hint sent to the IdP on SSO sign-in
      - `source` string — The user public_metadata key whose value is sent as the login_hint when mode is custom_attribute

## Response `200`

A SAML Connection

- union
  - object
    - `object` 'saml_connection', required
    - `id` string, required
    - `name` string, required
    - `domain` string, required
    - `domains` string[]
    - `idp_entity_id` string, nullable, required
    - `idp_sso_url` string, nullable, required
    - `idp_certificate` string, nullable, required
    - `idp_certificate_issued_at` integer, nullable, required — Unix timestamp (milliseconds) of the start of the IdP certificate validity window (X.509 NotBefore). Null when no certificate is configured.
    - `idp_certificate_expires_at` integer, nullable, required — Unix timestamp (milliseconds) of the end of the IdP certificate validity window (X.509 NotAfter). Null when no certificate is configured.
    - `idp_metadata_url` string, nullable
    - `idp_metadata` string, nullable
    - `acs_url` string, required
    - `sp_entity_id` string, required
    - `sp_metadata_url` string, required
    - `organization_id` string, nullable
    - `attribute_mapping` SAMLConnectionAttributeMapping
      - `user_id` string, required
      - `email_address` string, required
      - `first_name` string, required
      - `last_name` string, required
    - `active` boolean, required
    - `provider` string, required
    - `user_count` integer, required
    - `sync_user_attributes` boolean, required
    - `allow_subdomains` boolean, required
    - `allow_idp_initiated` boolean, required
    - `disable_additional_identifications` boolean, required
    - `allow_organization_account_linking` boolean, required
    - `force_authn` boolean, required — Enable or deactivate ForceAuthn
    - `login_hint` SAMLConnectionLoginHint, required — Configuration for the login_hint sent to the IdP on SSO sign-in
      - `mode` 'email_address' | 'custom_attribute' | 'off', required — Controls the login_hint sent to the IdP on SSO sign-in
      - `source` string — The user public_metadata key whose value is sent as the login_hint when mode is custom_attribute
    - `enterprise_connection_id` string, nullable
    - `created_at` integer, required — Unix timestamp of creation.
    - `updated_at` integer, required — Unix timestamp of last update.
  - object
    - `object` 'saml_connection', required
    - `id` string, required
    - `name` string, required
    - `domain` string
    - `domains` string[], required
    - `idp_entity_id` string, nullable, required
    - `idp_sso_url` string, nullable, required
    - `idp_certificate` string, nullable, required
    - `idp_certificate_issued_at` integer, nullable, required — Unix timestamp (milliseconds) of the start of the IdP certificate validity window (X.509 NotBefore). Null when no certificate is configured.
    - `idp_certificate_expires_at` integer, nullable, required — Unix timestamp (milliseconds) of the end of the IdP certificate validity window (X.509 NotAfter). Null when no certificate is configured.
    - `idp_metadata_url` string, nullable
    - `idp_metadata` string, nullable
    - `acs_url` string, required
    - `sp_entity_id` string, required
    - `sp_metadata_url` string, required
    - `organization_id` string, nullable
    - `attribute_mapping` SAMLConnectionAttributeMapping
      - `user_id` string, required
      - `email_address` string, required
      - `first_name` string, required
      - `last_name` string, required
    - `active` boolean, required
    - `provider` string, required
    - `user_count` integer, required
    - `sync_user_attributes` boolean, required
    - `allow_subdomains` boolean, required
    - `allow_idp_initiated` boolean, required
    - `disable_additional_identifications` boolean, required
    - `allow_organization_account_linking` boolean, required
    - `force_authn` boolean, required — Enable or deactivate ForceAuthn
    - `login_hint` SAMLConnectionLoginHint, required — Configuration for the login_hint sent to the IdP on SSO sign-in
      - `mode` 'email_address' | 'custom_attribute' | 'off', required — Controls the login_hint sent to the IdP on SSO sign-in
      - `source` string — The user public_metadata key whose value is sent as the login_hint when mode is custom_attribute
    - `enterprise_connection_id` string, nullable
    - `created_at` integer, required — Unix timestamp of creation.
    - `updated_at` integer, required — Unix timestamp of last update.

## Other responses

- `402` — Payment required
- `403` — Authorization invalid
- `404` — Resource not found
- `409` — Request was not successful
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/versions/cf036e7951d3/schema)