Clerk API (unofficial showcase)
POST/enterprise_connections

Create an enterprise connection

Creates a new enterprise connection for an identity provider and associates it with one or more domains. Supply name, provider, and at least one valid fully qualified domain name in domains; choose saml or oidc settings to configure the connection for the selected provider. When active is true, provide IdP metadata in saml for SAML connections.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

9 body fields

Configuration for the new enterprise connection. Include name, provider, and domains; the connection-specific saml and oidc objects apply to their corresponding provider types.

namestringrequired
The display name of the connection
providerstringrequired
The identity provider (e.g. saml_custom, oidc_custom, oidc_github_enterprise, oidc_gitlab)
Allowed:saml_customsaml_oktasaml_googlesaml_microsoftoidc_customoidc_github_enterpriseoidc_gitlab
domainsarray<string>required
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_idstringoptional
Organization ID when the connection is linked to an organization
allow_organization_account_linkingbooleanoptional
Whether this connection supports account linking via organization membership
activebooleanoptional
Whether the enterprise connection is active. When true, IdP metadata must be provided via the `saml` object.
samlobjectoptional
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.
oidcobjectoptional
OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. provider is oidc_custom, oidc_github_enterprise, or oidc_gitlab).
custom_attributesarray<object>optional
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.

6 status codes
201Returns the created enterprise connection, including its ID, name, provider, active state, domains, timestamps, and applicable SAML or OIDC configuration.
objectstringrequired
Allowed:enterprise_connection
idstringrequired
The enterprise connection ID
namestringrequired
The display name of the connection
providerstringrequired
logo_public_urlstringoptional
activebooleanrequired
Whether the enterprise connection is active
domainsarray<string>required
Domains associated with the enterprise connection
organization_idstringoptional
Organization ID when the connection is linked to an organization
sync_user_attributesbooleanoptional
Controls whether to update the user's attributes on each sign-in
disable_additional_identificationsbooleanoptional
When true, users cannot add additional identifications when using this connection
allow_organization_account_linkingbooleanoptional
Whether this connection supports account linking via organization membership
custom_attributesarray<object>optional
Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning
saml_connectionobjectoptional
Present when the enterprise connection uses SAML
oauth_configobjectoptional
Present when the enterprise connection uses OIDC or EASIE
created_atintegerrequired
Unix timestamp in milliseconds when the connection was created
updated_atintegerrequired
Unix timestamp in milliseconds when the connection was last updated
402Returned when payment is required to create the enterprise connection.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Returned when authorization is invalid for the request.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Returned when the requested resource is not found.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
409Returned when the request is not successful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 402 is returned when payment is required, a 403 when authorization is invalid, and a 404 when the requested resource is not found. A 409 is returned when the request is unsuccessful, and a 422 when request parameters are invalid. The body must include name, provider, and domains; provider must be one of the documented values, and domains must contain at least one valid fully qualified domain name.