openapi: 3.0.3 info: title: Clerk Backend Account Portal Enterprise 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](https://clerk.com/docs/versioning/available-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: Enterprise Connections description: 'An Enterprise Connection holds configuration data required for facilitating an enterprise SSO flow between your Clerk instance and an identity provider.' externalDocs: url: https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/overview paths: /enterprise_connections: get: operationId: ListEnterpriseConnections x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: list summary: List Enterprise Connections description: 'Returns the list of enterprise connections for the instance. Results can be paginated using the optional `limit` and `offset` query parameters.' tags: - Enterprise Connections parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - name: organization_id in: query required: false description: Filter enterprise connections by organization ID schema: type: string - name: active in: query required: false description: Filter by active status. If true, only active connections are returned. If false, only inactive connections are returned. If omitted, all connections are returned. schema: type: boolean responses: '200': $ref: '#/components/responses/EnterpriseConnections' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: create summary: Create an Enterprise Connection description: Create a new enterprise connection. tags: - Enterprise Connections requestBody: content: application/json: schema: type: object additionalProperties: false required: - name - provider - domains properties: name: type: string description: The display name of the connection provider: type: string description: The identity provider (e.g. saml_custom, oidc_custom, oidc_github_enterprise, oidc_gitlab) enum: - saml_custom - saml_okta - saml_google - saml_microsoft - oidc_custom - oidc_github_enterprise - oidc_gitlab domains: type: array items: type: string minItems: 1 description: 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_id: type: string description: Organization ID when the connection is linked to an organization nullable: true allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership nullable: true active: type: boolean description: Whether the enterprise connection is active. When true, IdP metadata must be provided via the `saml` object. nullable: true saml: type: object description: '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.' nullable: true additionalProperties: false properties: idp_entity_id: type: string description: IdP entity ID nullable: true idp_sso_url: type: string description: IdP SSO URL nullable: true idp_certificate: type: string description: IdP certificate (PEM) nullable: true idp_metadata_url: type: string description: URL to IdP metadata nullable: true idp_metadata: type: string description: Raw IdP metadata XML nullable: true attribute_mapping: type: object description: Attribute mapping for SAML attributes nullable: true additionalProperties: false properties: user_id: type: string nullable: true email_address: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true allow_subdomains: type: boolean nullable: true allow_idp_initiated: type: boolean nullable: true force_authn: type: boolean nullable: true oidc: type: object description: OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. provider is oidc_custom, oidc_github_enterprise, or oidc_gitlab). nullable: true additionalProperties: false properties: client_id: type: string description: OIDC client ID nullable: true client_secret: type: string description: OIDC client secret nullable: true discovery_url: type: string description: OIDC discovery URL nullable: true auth_url: type: string description: OIDC authorization URL nullable: true token_url: type: string description: OIDC token URL nullable: true user_info_url: type: string description: OIDC userinfo URL nullable: true requires_pkce: type: boolean description: Whether PKCE is required (must be true for public clients with no client secret) nullable: true custom_attributes: type: array description: 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. items: type: object additionalProperties: false required: - name - key properties: name: type: string description: Display name for the custom attribute minLength: 1 key: type: string description: Key used to store the attribute in the user's metadata minLength: 1 pattern: ^[^_][A-Za-z0-9_-]*$ sso_path: type: string description: Path to extract the attribute value from SSO claims scim_path: type: string description: GJSON path to extract the attribute value from SCIM user resources responses: '201': $ref: '#/components/responses/EnterpriseConnection' '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' /enterprise_connections/{enterprise_connection_id}: get: operationId: GetEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: get summary: Retrieve an Enterprise Connection description: Fetches the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path. tags: - Enterprise Connections parameters: - in: path name: enterprise_connection_id required: true schema: type: string description: The ID of the enterprise connection responses: '200': $ref: '#/components/responses/EnterpriseConnection' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: update summary: Update an Enterprise Connection description: '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.' tags: - Enterprise Connections parameters: - in: path name: enterprise_connection_id required: true schema: type: string description: The ID of the enterprise connection to update requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The display name of the enterprise connection nullable: true domains: type: array items: type: string description: '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).' nullable: true active: type: boolean description: 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. nullable: true sync_user_attributes: type: boolean description: Whether to sync user attributes on sign-in nullable: true disable_additional_identifications: type: boolean description: Whether to disable additional identifications nullable: true allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership nullable: true organization_id: type: string description: 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. nullable: true saml: type: object description: '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.' nullable: true additionalProperties: false properties: name: type: string description: Display name of the SAML connection nullable: true idp_entity_id: type: string description: IdP entity ID nullable: true idp_sso_url: type: string description: IdP SSO URL nullable: true idp_certificate: type: string description: IdP certificate (PEM) nullable: true idp_metadata_url: type: string description: URL to IdP metadata nullable: true idp_metadata: type: string description: Raw IdP metadata XML nullable: true attribute_mapping: type: object description: Attribute mapping for SAML attributes nullable: true additionalProperties: false properties: user_id: type: string nullable: true email_address: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true allow_subdomains: type: boolean nullable: true allow_idp_initiated: type: boolean nullable: true force_authn: type: boolean nullable: true oidc: type: object description: OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. oidc_custom, oidc_github_enterprise, or oidc_gitlab). nullable: true additionalProperties: false properties: client_id: type: string description: OIDC client ID nullable: true client_secret: type: string description: OIDC client secret nullable: true discovery_url: type: string description: OIDC discovery URL nullable: true auth_url: type: string description: OIDC authorization URL nullable: true token_url: type: string description: OIDC token URL nullable: true user_info_url: type: string description: OIDC userinfo URL nullable: true requires_pkce: type: boolean description: Whether PKCE is required (must be true for public clients with no client secret) nullable: true custom_attributes: type: array description: 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. nullable: true items: type: object additionalProperties: false required: - name - key properties: name: type: string description: Display name for the custom attribute minLength: 1 key: type: string description: Key used to store the attribute in the user's metadata minLength: 1 pattern: ^[^_][A-Za-z0-9_-]*$ sso_path: type: string description: Path to extract the attribute value from SSO claims scim_path: type: string description: GJSON path to extract the attribute value from SCIM user resources responses: '200': $ref: '#/components/responses/EnterpriseConnection' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: delete summary: Delete an Enterprise Connection description: Deletes the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path. tags: - Enterprise Connections parameters: - in: path name: enterprise_connection_id required: true schema: type: string description: The ID of the enterprise 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: AuthorizationInvalid: description: Authorization invalid content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' ClerkErrors: description: Request was not successful content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' ResourceNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' DeletedObject: description: Deleted Object content: application/json: schema: $ref: '#/components/schemas/DeletedObject' EnterpriseConnection: description: An enterprise connection content: application/json: schema: $ref: '#/components/schemas/EnterpriseConnection' UnprocessableEntity: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' PaymentRequired: description: Payment required content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' EnterpriseConnections: description: A list of enterprise connections content: application/json: schema: $ref: '#/components/schemas/EnterpriseConnections' schemas: ClerkError: type: object properties: message: type: string long_message: type: string code: type: string meta: type: object required: - message - long_message - code EnterpriseConnections: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/EnterpriseConnection' total_count: type: integer format: int64 description: Total number of enterprise connections required: - data - total_count EnterpriseConnection: type: object required: - id - name - provider - active - domains - authenticatable - created_at - updated_at properties: id: type: string description: The enterprise connection ID name: type: string description: The display name of the connection provider: type: string logo_public_url: type: string nullable: true active: type: boolean description: Whether the enterprise connection is active domains: type: array items: type: string description: Domains associated with the enterprise connection organization_id: type: string description: Organization ID when the connection is linked to an organization nullable: true sync_user_attributes: type: boolean description: Controls whether to update the user's attributes on each sign-in disable_additional_identifications: type: boolean description: When true, users cannot add additional identifications when using this connection allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership custom_attributes: type: array description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning items: type: object additionalProperties: false required: - name - key properties: name: type: string description: Display name for the custom attribute key: type: string description: Key used to store the attribute in the user's public/private/unsafe metadata sso_path: type: string description: Path to extract the attribute value from SSO claims (SAML assertions or OIDC claims) scim_path: type: string description: GJSON path to extract the attribute value from SCIM user resources saml_connection: type: object nullable: true description: Present when the enterprise connection uses SAML properties: id: type: string description: SAML connection ID name: type: string description: SAML connection display name idp_entity_id: type: string description: IdP entity ID (optional, when connection details are loaded) nullable: true idp_sso_url: type: string description: IdP SSO URL (optional, when connection details are loaded) nullable: true idp_metadata_url: type: string description: IdP metadata URL (optional, when connection details are loaded) nullable: true acs_url: type: string description: Assertion Consumer Service URL nullable: true sp_entity_id: type: string description: Service Provider entity ID nullable: true sp_metadata_url: type: string description: Service Provider metadata URL nullable: true active: type: boolean description: Whether the SAML connection is active allow_idp_initiated: type: boolean description: Whether IdP-initiated SSO is allowed allow_subdomains: type: boolean description: Whether subdomains are allowed for domain matching force_authn: type: boolean description: Whether to force re-authentication oauth_config: type: object nullable: true description: Present when the enterprise connection uses OIDC or EASIE properties: id: type: string description: OAuth config ID name: type: string description: Custom OIDC provider display name provider_key: type: string description: OAuth provider key (e.g. oidc_custom, oidc_ghe_*, oidc_gitlab_ent_*) client_id: type: string description: OAuth client ID nullable: true discovery_url: type: string description: OIDC discovery URL nullable: true auth_url: type: string description: OAuth authorization endpoint URL (present when configured or resolved from discovery) nullable: true token_url: type: string description: OAuth token endpoint URL (present when configured or resolved from discovery) nullable: true user_info_url: type: string description: OIDC userinfo endpoint URL (present when configured or resolved from discovery) nullable: true requires_pkce: type: boolean description: Whether PKCE is required for this OAuth client logo_public_url: type: string description: Logo URL for the provider nullable: true created_at: type: integer format: int64 description: Unix timestamp in milliseconds when the config was created updated_at: type: integer format: int64 description: Unix timestamp in milliseconds when the config was last updated created_at: type: integer format: int64 description: Unix timestamp in milliseconds when the connection was created updated_at: type: integer format: int64 description: Unix timestamp in milliseconds when the connection was last updated 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 ClerkErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/ClerkError' meta: type: object clerk_trace_id: type: string required: - errors parameters: 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 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 securitySchemes: bearerAuth: type: http scheme: bearer description: Secret key, obtained under "API Keys" in the Clerk Dashboard. bearerFormat: sk__ 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