---
title: "Update an enterprise connection"
method: PATCH
path: "/enterprise_connections/{enterprise_connection_id}"
tags: ["Enterprise Connections"]
---

# Update an enterprise connection

`PATCH /enterprise_connections/{enterprise_connection_id}`

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.

## Path parameters

- `enterprise_connection_id` string, required

## Request body

- object
  - `name` string, nullable — The display name of the enterprise connection
  - `domains` string[], nullable — 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).
  - `active` boolean, nullable — 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.
  - `sync_user_attributes` boolean, nullable — Whether to sync user attributes on sign-in
  - `disable_additional_identifications` boolean, nullable — Whether to disable additional identifications
  - `allow_organization_account_linking` boolean, nullable — Whether this connection supports account linking via organization membership
  - `organization_id` string, nullable — 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.
  - `saml` object, nullable — 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.
    - `name` string, nullable — Display name of the SAML connection
    - `idp_entity_id` string, nullable — IdP entity ID
    - `idp_sso_url` string, nullable — IdP SSO URL
    - `idp_certificate` string, nullable — IdP certificate (PEM)
    - `idp_metadata_url` string, nullable — URL to IdP metadata
    - `idp_metadata` string, nullable — Raw IdP metadata XML
    - `attribute_mapping` object, nullable — Attribute mapping for SAML attributes
      - `user_id` string, nullable
      - `email_address` string, nullable
      - `first_name` string, nullable
      - `last_name` string, nullable
    - `allow_subdomains` boolean, nullable
    - `allow_idp_initiated` boolean, nullable
    - `force_authn` boolean, nullable
    - `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
  - `oidc` object, nullable — OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. oidc_custom, oidc_github_enterprise, or oidc_gitlab).
    - `client_id` string, nullable — OIDC client ID
    - `client_secret` string, nullable — OIDC client secret
    - `discovery_url` string, nullable — OIDC discovery URL
    - `auth_url` string, nullable — OIDC authorization URL
    - `token_url` string, nullable — OIDC token URL
    - `user_info_url` string, nullable — OIDC userinfo URL
    - `requires_pkce` boolean, nullable — Whether PKCE is required (must be true for public clients with no client secret)
  - `custom_attributes` object[], nullable — 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.
    - `name` string, required — Display name for the custom attribute
    - `key` string, required — Key used to store the attribute in the user's metadata
    - `sso_path` string — Path to extract the attribute value from SSO claims
    - `scim_path` string — GJSON path to extract the attribute value from SCIM user resources
    - `multi_valued` boolean — When true, the attribute supports multiple values; values from the IdP are written to public_metadata as an array. Defaults to false.

## Response `200`

An enterprise connection

- EnterpriseConnection
  - `object` 'enterprise_connection', required
  - `id` string, required — The enterprise connection ID
  - `name` string, required — The display name of the connection
  - `provider` string, required
  - `logo_public_url` string, nullable
  - `active` boolean, required — Whether the enterprise connection is active
  - `domains` string[], required — Domains associated with the enterprise connection
  - `organization_id` string, nullable — Organization ID when the connection is linked to an organization
  - `sync_user_attributes` boolean — Controls whether to update the user's attributes on each sign-in
  - `disable_additional_identifications` boolean — When true, users cannot add additional identifications when using this connection
  - `allow_organization_account_linking` boolean — Whether this connection supports account linking via organization membership
  - `custom_attributes` object[] — Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning
    - `name` string, required — Display name for the custom attribute
    - `key` string, required — Key used to store the attribute in the user's public/private/unsafe metadata
    - `sso_path` string — Path to extract the attribute value from SSO claims (SAML assertions or OIDC claims)
    - `scim_path` string — GJSON path to extract the attribute value from SCIM user resources
    - `multi_valued` boolean — When true, the attribute supports multiple values; values from the IdP are written to public_metadata as an array. Defaults to false.
  - `saml_connection` object, nullable — Present when the enterprise connection uses SAML
    - `id` string — SAML connection ID
    - `name` string — SAML connection display name
    - `idp_entity_id` string, nullable — IdP entity ID (optional, when connection details are loaded)
    - `idp_sso_url` string, nullable — IdP SSO URL (optional, when connection details are loaded)
    - `idp_metadata_url` string, nullable — IdP metadata URL (optional, when connection details are loaded)
    - `acs_url` string, nullable — Assertion Consumer Service URL
    - `sp_entity_id` string, nullable — Service Provider entity ID
    - `sp_metadata_url` string, nullable — Service Provider metadata URL
    - `active` boolean — Whether the SAML connection is active
    - `allow_idp_initiated` boolean — Whether IdP-initiated SSO is allowed
    - `allow_subdomains` boolean — Whether subdomains are allowed for domain matching
    - `force_authn` boolean — Whether to force re-authentication
    - `login_hint` object — 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
  - `oauth_config` object, nullable — Present when the enterprise connection uses OIDC or EASIE
    - `id` string — OAuth config ID
    - `name` string — Custom OIDC provider display name
    - `provider_key` string — OAuth provider key (e.g. oidc_custom, oidc_ghe_*, oidc_gitlab_ent_*)
    - `client_id` string, nullable — OAuth client ID
    - `discovery_url` string, nullable — OIDC discovery URL
    - `auth_url` string, nullable — OAuth authorization endpoint URL (present when configured or resolved from discovery)
    - `token_url` string, nullable — OAuth token endpoint URL (present when configured or resolved from discovery)
    - `user_info_url` string, nullable — OIDC userinfo endpoint URL (present when configured or resolved from discovery)
    - `requires_pkce` boolean — Whether PKCE is required for this OAuth client
    - `logo_public_url` string, nullable — Logo URL for the provider
    - `created_at` integer — Unix timestamp in milliseconds when the config was created
    - `updated_at` integer — Unix timestamp in milliseconds when the config was last updated
  - `created_at` integer, required — Unix timestamp in milliseconds when the connection was created
  - `updated_at` integer, required — Unix timestamp in milliseconds when the connection was last updated

## Other responses

- `400` — Request was not successful
- `402` — Payment required
- `403` — Authorization invalid
- `404` — Resource not found
- `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/revisions/cf036e7951d3/schema)