Skip to main content

createEnterpriseConnection()

Creates a new enterprise connection.

Returns the created EnterpriseConnection object.

function createEnterpriseConnection(params: CreateEnterpriseConnectionParams): Promise<EnterpriseConnection>

CreateEnterpriseConnectionParams

  • Name
    active?
    Type
    boolean
    Description

    Whether the enterprise connection should be active.

  • Name
    allowOrganizationAccountLinking?
    Type
    boolean
    Description

    Whether existing users who are members of the organization can link their account to their enterprise identity. If false, only sign-up flows apply.

  • Name
    authenticatable?
    Type
    boolean
    Description

    Whether the enterprise connection can be used for sign-in and sign-up. Requires the authenticatable enterprise connections feature to be enabled for the instance.

  • Name
    customAttributes?
    Type
    { key: string; multiValued?: boolean; name: string; scimPath?: string; ssoPath?: string; }[]
    Description

    The custom attribute mappings for the enterprise connection.

  • Name
    customAttributes?.key
    Type
    string
    Description

    The key to store the custom attribute under.

  • Name
    customAttributes?.multiValued?
    Type
    boolean
    Description

    Whether the custom attribute holds multiple values.

  • Name
    customAttributes?.name
    Type
    string
    Description

    The display name of the custom attribute.

  • Name
    customAttributes?.scimPath?
    Type
    string
    Description

    The SCIM attribute path to read the value from.

  • Name
    customAttributes?.ssoPath?
    Type
    string
    Description

    The SSO (SAML or OIDC) attribute path to read the value from.

  • Name
    disableJitProvisioning?
    Type
    boolean
    Description

    Whether Just-in-Time (JIT) provisioning of users is disabled for the enterprise connection.

  • Name
    domains
    Type
    string[]
    Description

    The Verified Domains of the enterprise connection. Must contain at least one domain.

  • Name
    name
    Type
    string
    Description

    The name of the enterprise connection.

  • Name
    oidc?
    Type
    { authUrl?: string; clientId?: string; clientSecret?: string; discoveryUrl?: string; requiresPkce?: boolean; tokenUrl?: string; userInfoUrl?: string; }
    Description

    Configuration for if the enterprise connection uses OAuth (OIDC).

  • Name
    oidc.authUrl?
    Type
    string
    Description

    The OAuth (OIDC) authorization URL.

  • Name
    oidc.clientId?
    Type
    string
    Description

    The OAuth (OIDC) client ID.

  • Name
    oidc.clientSecret?
    Type
    string
    Description

    The OAuth (OIDC) client secret.

  • Name
    oidc.discoveryUrl?
    Type
    string
    Description

    The OAuth (OIDC) discovery URL.

  • Name
    oidc.requiresPkce?
    Type
    boolean
    Description

    Whether the OAuth (OIDC) requires PKCE. Must be true for public clients with no client secret.

  • Name
    oidc.tokenUrl?
    Type
    string
    Description

    The OAuth (OIDC) token URL.

  • Name
    oidc.userInfoUrl?
    Type
    string
    Description

    The OAuth (OIDC) user info URL.

  • Name
    organizationId?
    Type
    string
    Description

    The organization ID of the enterprise connection.

  • Name
    provider
    Type
    OrganizationEnterpriseConnectionProvider
    Description

    The identity provider (IdP) of the enterprise connection. For example, 'saml_custom' or 'oidc_custom'.

  • Name
    saml?
    Type
    { allowIdpInitiated?: boolean; allowSubdomains?: boolean; attributeMapping?: { emailAddress?: string | null; firstName?: string | null; lastName?: string | null; userId?: string | null; }; forceAuthn?: boolean; idpCertificate?: string; idpEntityId?: string; idpMetadata?: string; idpMetadataUrl?: string; idpSsoUrl?: string; loginHint?: { mode: "custom_attribute"; source: string; } | { mode: "email_address" | "off"; source?: never; }; }
    Description

    Configuration for if the enterprise connection uses SAML.

  • Name
    saml.allowIdpInitiated?
    Type
    boolean
    Description

    Whether the SAML connection allows Identity Provider (IdP) initiated flows.

  • Name
    saml.allowSubdomains?
    Type
    boolean
    Description

    Whether the SAML connection allows users with an email address subdomain to use it.

  • Name
    saml.attributeMapping?
    Type
    { emailAddress?: string | null; firstName?: string | null; lastName?: string | null; userId?: string | null; }
    Description

    The attribute mapping for the SAML connection.

  • Name
    saml.attributeMapping.emailAddress?
    Type
    string | null
    Description

    The attribute mapping for the email address.

  • Name
    saml.attributeMapping.firstName?
    Type
    string | null
    Description

    The attribute mapping for the first name.

  • Name
    saml.attributeMapping.lastName?
    Type
    string | null
    Description

    The attribute mapping for the last name.

  • Name
    saml.attributeMapping.userId?
    Type
    string | null
    Description

    The attribute mapping for the user ID.

  • Name
    saml.forceAuthn?
    Type
    boolean
    Description

    Whether the SAML connection requires force authentication.

  • Name
    saml.idpCertificate?
    Type
    string
    Description

    The IdP certificate (PEM) for the SAML connection.

  • Name
    saml.idpEntityId?
    Type
    string
    Description

    The IdP Entity ID for the SAML connection.

  • Name
    saml.idpMetadata?
    Type
    string
    Description

    The raw IdP metadata XML for the SAML connection.

  • Name
    saml.idpMetadataUrl?
    Type
    string
    Description

    The IdP metadata URL for the SAML connection.

  • Name
    saml.idpSsoUrl?
    Type
    string
    Description

    The IdP Single-Sign On URL for the SAML connection.

  • Name
    saml.loginHint?
    Type
    { mode: "custom_attribute"; source: string; } | { mode: "email_address" | "off"; source?: never; }
    Description

    Configuration for the login_hint the SAML connection sends to the IdP.

  • Name
    syncUserAttributes?
    Type
    boolean
    Description

    Whether the enterprise connection should sync user attributes between the IdP and Clerk. Deprecated. The Backend API does not support this parameter on create and ignores it. Use updateEnterpriseConnection() to set it.

Usage

Note

Using clerkClient varies based on the SDK you're using. Refer to the overview for usage details, including guidance on how to access the userId and other properties.

const response = await clerkClient.enterpriseConnections.createEnterpriseConnection({
  name: 'Google',
  organizationId: 'org_123',
  oidc: {
    authUrl: 'https://example.com/auth',
    clientId: '1234567890',
    clientSecret: '1234567890',
    discoveryUrl: 'https://example.com/discovery',
    requiresPkce: false,
    tokenUrl: 'https://example.com/token',
    userInfoUrl: 'https://example.com/userinfo',
  },
})

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint POST/enterprise_connections. See the BAPI reference for more information.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub