Connections - Create Connection

Reference

Service:: Core

API Version:: v1

[!NOTE]> This API is in preview.

Creates a connection.
To encrypt credentials, see Configure credentials programmatically.

Permissions

If creating a gateway connection, the caller must have permissions for the gateway.

Required Delegated Scopes

Connection.ReadWrite.All

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity	Support
User	Yes
Service principal and Managed identities	Yes

Interface

POST https://api.fabric.microsoft.com/v1/connections

Request Body

The request body can be one of the following:

Name	Description
CreateCloudConnectionRequest
CreateOnPremisesConnectionRequest
CreateVirtualNetworkGatewayConnectionRequest

CreateCloudConnectionRequest

Name	Required	Type	Description
connectionDetails	True	CreateConnectionDetails	The connection details of the connection.
connectivityType	True	string: ShareableCloud	The connectivity type of the connection.
credentialDetails	True	CreateCredentialDetails	The credential details of the connection.
displayName	True	string	The display name of the connection. Maximum length is 200 characters.
privacyLevel	True	PrivacyLevel	The privacy level of the connection.

CreateOnPremisesConnectionRequest

Name	Required	Type	Description
connectionDetails	True	CreateConnectionDetails	The connection details of the connection.
connectivityType	True	string: OnPremisesGateway	The connectivity type of the connection.
credentialDetails	True	CreateOnPremisesCredentialDetails	The credential details of the connection.
displayName	True	string	The display name of the connection. Maximum length is 200 characters.
gatewayId	True	string	The object ID of the primary gateway of the on-premises gateway that the connection is created under.
privacyLevel	True	PrivacyLevel	The privacy level of the connection.

CreateVirtualNetworkGatewayConnectionRequest

Name	Required	Type	Description
connectionDetails	True	CreateConnectionDetails	The connection details of the connection.
connectivityType	True	string: VirtualNetworkGateway	The connectivity type of the connection.
credentialDetails	True	CreateCredentialDetails	The credential details of the connection.
displayName	True	string	The display name of the connection. Maximum length is 200 characters.
gatewayId	True	string	The object ID of the virtual network gateway that the connection is created under.
privacyLevel	True	PrivacyLevel	The privacy level of the connection.

Responses

Name	Type	Description
201 Created	Connection	Created. The operation was successful.
Other Status Codes	ErrorResponse	Common error codes: DuplicateConnectionName - The connection name is already in use. InvalidConnectionDetails - The ConnectionDetails input provided is not valid. InvalidCredentialDetails - The CredentialDetails input provided is not valid. IncorrectCredentials - Failed to establish connection using the Credentials input. CreateGatewayConnectionFailed - Failed to create gateway connection.

Name

Type

Description

201 Created

Connection

Created. The operation was successful.

Other Status Codes

ErrorResponse

Common error codes:

DuplicateConnectionName - The connection name is already in use.
InvalidConnectionDetails - The ConnectionDetails input provided is not valid.
InvalidCredentialDetails - The CredentialDetails input provided is not valid.
IncorrectCredentials - Failed to establish connection using the Credentials input.
CreateGatewayConnectionFailed - Failed to create gateway connection.

Examples

Cloud example

Virtual network gateway example

Cloud example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/connections

{
  "connectivityType": "ShareableCloud",
  "displayName": "ContosoCloudConnection",
  "connectionDetails": {
    "type": "SQL",
    "creationMethod": "SQL",
    "parameters": [
      {
        "dataType": "Text",
        "name": "server",
        "value": "contoso.database.windows.net"
      },
      {
        "dataType": "Text",
        "name": "database",
        "value": "sales"
      }
    ]
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false,
    "credentials": {
      "credentialType": "Basic",
      "username": "admin",
      "password": "********"
    }
  }
}

Sample response

Status code:: 201

{
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "displayName": "ContosoCloudConnection",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

Virtual network gateway example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/connections

{
  "connectivityType": "VirtualNetworkGateway",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "displayName": "ContosoVirtualNetworkGatewayConnection",
  "connectionDetails": {
    "type": "SQL",
    "creationMethod": "SQL",
    "parameters": [
      {
        "dataType": "Text",
        "name": "server",
        "value": "contoso.database.windows.net"
      },
      {
        "dataType": "Text",
        "name": "database",
        "value": "sales"
      }
    ]
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "singleSignOnType": "None",
    "connectionEncryption": "Encrypted",
    "skipTestConnection": false,
    "credentials": {
      "credentialType": "Basic",
      "username": "admin",
      "password": "*********"
    }
  }
}

Sample response

Status code:: 201

{
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "displayName": "ContosoVirtualNetworkGatewayConnection",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "connectivityType": "VirtualNetworkGateway",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "Encrypted",
    "skipTestConnection": false
  }
}

Definitions

Name	Description
AnonymousCredentials	Credentials for Anonymous CredentialType.
BasicCredentials	Credentials for Basic CredentialType.
Connection
ConnectionDetailsBooleanParameter	ConnectionDetailsParameter for boolean dataType.
ConnectionDetailsDateParameter	ConnectionDetailsParameter for date dataType.
ConnectionDetailsDateTimeParameter	ConnectionDetailsParameter for dateTime dataType.
ConnectionDetailsDateTimeZoneParameter	ConnectionDetailsParameter for dateTimeZone dataType.
ConnectionDetailsDurationParameter	ConnectionDetailsParameter for duration dataType.
ConnectionDetailsNumberParameter	ConnectionDetailsParameter for number dataType.
ConnectionDetailsTextParameter	ConnectionDetailsParameter for text dataType.
ConnectionDetailsTimeParameter	ConnectionDetailsParameter for time dataType.
ConnectionEncryption	The connection encryption type of the connection. Additional connection encryption values may be added over time.
ConnectivityType	The connectivity type of the connection. Additional connectivity types may be added over time.
CreateCloudConnectionRequest
CreateConnectionDetails	The connection details input for create operations.
CreateCredentialDetails	The credential details input for creating a connection.
CreateOnPremisesConnectionRequest
CreateOnPremisesCredentialDetails	The credential details input for creating an on-premises gateway connection.
CreateVirtualNetworkGatewayConnectionRequest
CredentialType	The credential type of the connection. Additional credential types may be added over time.
DataType	The data type of the connection creation parameter value. Additional data type values may be added over time.
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
KeyCredentials	Credentials for Key CredentialType.
ListConnectionDetails	The connection details output for list operations.
ListCredentialDetails	The credential details returned when fetching a connection.
OnPremisesCredentialEntry	A gateway ID and its encrypted serialized credentials.
OnPremisesGatewayCredentials	Credentials for authenticating through an on-premises gateway.
PrivacyLevel	The privacy level setting of the connection. Additional privacy levels may be added over time.
ServicePrincipalCredentials	Credentials for ServicePrincipal CredentialType.
SharedAccessSignatureCredentials	Credentials for SharedAccessSignature CredentialType.
SingleSignOnType	The single sign-on type of the connection. Additional single sign on types may be added over time.
WindowsCredentials	Credentials for Windows CredentialType.
WindowsWithoutImpersonationCredentials	Credentials for WindowsWithoutImpersonation CredentialType.
WorkspaceIdentityCredentials	Credentials for WorkspaceIdentity CredentialType.

AnonymousCredentials

Credentials for Anonymous CredentialType.

Name	Type	Description
credentialType	string: Anonymous	The credential type of the connection.

BasicCredentials

Credentials for Basic CredentialType.

Name	Type	Description
credentialType	string: Basic	The credential type of the connection.
password	string	The password.
username	string	The username.

Connection

Name	Type	Description
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectivityType	ConnectivityType	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string	The gateway object ID of the connection.
id	string	The object ID of the connection.
privacyLevel	PrivacyLevel	The privacy level of the connection.

ConnectionDetailsBooleanParameter

ConnectionDetailsParameter for boolean dataType.

Name	Type	Description
dataType	string: Boolean	The data type of the parameter.
name	string	The name of the parameter.
value	boolean	The boolean value.

ConnectionDetailsDateParameter

ConnectionDetailsParameter for date dataType.

Name	Type	Description
dataType	string: Date	The data type of the parameter.
name	string	The name of the parameter.
value	string	The date value using YYYY-MM-DD format.

ConnectionDetailsDateTimeParameter

ConnectionDetailsParameter for dateTime dataType.

Name	Type	Description
dataType	string: DateTime	The data type of the parameter.
name	string	The name of the parameter.
value	string	The date time value using YYYY-MM-DDTHH:mm:ss.FFFZ format.

ConnectionDetailsDateTimeZoneParameter

ConnectionDetailsParameter for dateTimeZone dataType.

Name	Type	Description
dataType	string: DateTimeZone	The data type of the parameter.
name	string	The name of the parameter.
value	string	The date time zone value using YYYY-MM-DDTHH:mm:ss.FFF±hh:mm format.

ConnectionDetailsDurationParameter

ConnectionDetailsParameter for duration dataType.

Name	Type	Description
dataType	string: Duration	The data type of the parameter.
name	string	The name of the parameter.
value	string	The duration value using [-]P(n)DT(n)H(n)M(n)S format. For example: P3DT4H30M10S (for 3 days, 4 hours, 30 minutes, and 10 seconds).

ConnectionDetailsNumberParameter

ConnectionDetailsParameter for number dataType.

Name	Type	Description
dataType	string: Number	The data type of the parameter.
name	string	The name of the parameter.
value	number	The number value.

ConnectionDetailsTextParameter

ConnectionDetailsParameter for text dataType.

Name	Type	Description
dataType	string: Text	The data type of the parameter.
name	string	The name of the parameter.
value	string	The text value.

ConnectionDetailsTimeParameter

ConnectionDetailsParameter for time dataType.

Name	Type	Description
dataType	string: Time	The data type of the parameter.
name	string	The name of the parameter.
value	string	The time value using HH:mm:ss.FFFZ format.

ConnectionEncryption

The connection encryption type of the connection. Additional connection encryption values may be added over time.

Name	Type	Description
Any	string	The connection attempt is first made using an encrypted connection, then falls back to unencrypted connection if unsuccessful.
Encrypted	string	The connection attempt is made using an encrypted connection.
NotEncrypted	string	The connection attempt is made using an unencrypted connection.

ConnectivityType

The connectivity type of the connection. Additional connectivity types may be added over time.

Name	Type	Description
Automatic	string	The connection connects through the cloud using an implicit data connection. This option is only available for specific scenarios like semantic models that use Single Sign-On (SSO).”
None	string	The connection is not bound
OnPremisesGateway	string	The connection connects through an on-premises data gateway.
OnPremisesGatewayPersonal	string	The connection connects through a personal on-premises data gateway.
PersonalCloud	string	The connection connects through the cloud and cannot be shared with others.
ShareableCloud	string	The connection connects through the cloud and can be shared with others.
VirtualNetworkGateway	string	The connection connects through a virtual network data gateway.

CreateCloudConnectionRequest

Name	Type	Description
connectionDetails	CreateConnectionDetails	The connection details of the connection.
connectivityType	string: ShareableCloud	The connectivity type of the connection.
credentialDetails	CreateCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection. Maximum length is 200 characters.
privacyLevel	PrivacyLevel	The privacy level of the connection.

CreateConnectionDetails

The connection details input for create operations.

Name	Type	Description
creationMethod	string	The creation method used to create the connection.
parameters	ConnectionDetailsParameter[]: ConnectionDetailsBooleanParameter[] ConnectionDetailsDateParameter[] ConnectionDetailsDateTimeParameter[] ConnectionDetailsDateTimeZoneParameter[] ConnectionDetailsDurationParameter[] ConnectionDetailsNumberParameter[] ConnectionDetailsTextParameter[] ConnectionDetailsTimeParameter[]	The list of connection parameters.
type	string	The type of the connection.

CreateCredentialDetails

The credential details input for creating a connection.

Name	Type	Description
connectionEncryption	ConnectionEncryption	The connection encryption setting that is used during the test connection.
credentials	Credentials: AnonymousCredentials BasicCredentials KeyCredentials ServicePrincipalCredentials SharedAccessSignatureCredentials WindowsCredentials WindowsWithoutImpersonationCredentials WorkspaceIdentityCredentials	The credentials of the connection.
singleSignOnType	SingleSignOnType	The single sign-on type of the connection.
skipTestConnection	boolean	Whether the connection should skip the test connection during creation and update. True - Skip the test connection, False - Do not skip the test connection.

CreateOnPremisesConnectionRequest

Name	Type	Description
connectionDetails	CreateConnectionDetails	The connection details of the connection.
connectivityType	string: OnPremisesGateway	The connectivity type of the connection.
credentialDetails	CreateOnPremisesCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection. Maximum length is 200 characters.
gatewayId	string	The object ID of the primary gateway of the on-premises gateway that the connection is created under.
privacyLevel	PrivacyLevel	The privacy level of the connection.

CreateOnPremisesCredentialDetails

The credential details input for creating an on-premises gateway connection.

Name	Type	Description
connectionEncryption	ConnectionEncryption	The connection encryption setting that is used during the test connection.
credentials	OnPremisesGatewayCredentials	The credentials of the connection.
singleSignOnType	SingleSignOnType	The single sign-on type of the connection.
skipTestConnection	boolean	Whether the connection should skip the test connection during creation and update. True - Skip the test connection, False - Do not skip the test connection.

CreateVirtualNetworkGatewayConnectionRequest

Name	Type	Description
connectionDetails	CreateConnectionDetails	The connection details of the connection.
connectivityType	string: VirtualNetworkGateway	The connectivity type of the connection.
credentialDetails	CreateCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection. Maximum length is 200 characters.
gatewayId	string	The object ID of the virtual network gateway that the connection is created under.
privacyLevel	PrivacyLevel	The privacy level of the connection.

CredentialType

The credential type of the connection. Additional credential types may be added over time.

Name	Type	Description
Anonymous	string	Connection uses anonymous authentication to connect.
Basic	string	Connection uses basic authentication to connect.
Key	string	Connection uses key authentication to connect.
OAuth2	string	Connection uses OAuth 2.0 authentication to connect.
ServicePrincipal	string	Connection uses service principal authentication to connect.
SharedAccessSignature	string	Connection uses shared access signature (SAS) authentication to connect.
Windows	string	Connection uses Windows authentication to connect. Only supported for on-premises gateways.
WindowsWithoutImpersonation	string	Connection uses Windows (without the option for impersonation) authentication to connect. Only supported for on-premises gateways (personal mode).
WorkspaceIdentity	string	Connection uses workspace identity authentication to connect.

DataType

The data type of the connection creation parameter value. Additional data type values may be added over time.

Name	Type	Description
Boolean	string	Use boolean as the parameter input value. False - the value is false, True - the value is true.
Date	string	Use date as the parameter input value, using YYYY-MM-DD format.
DateTime	string	Use date time as the parameter input value, using YYYY-MM-DDTHH:mm:ss.FFFZ format.
DateTimeZone	string	Use date time zone as the parameter input value, using YYYY-MM-DDTHH:mm:ss.FFF±hh:mm format.
Duration	string	Use duration as the parameter input value, using [-]P(n)DT(n)H(n)M(n)S format. For example: P3DT4H30M10S (for 3 days, 4 hours, 30 minutes, and 10 seconds).
Number	string	Use number as the parameter input value (integer or floating point).
Text	string	Use text as the parameter input value.
Time	string	Use time as the parameter input value, using HH:mm:ss.FFFZ format.

ErrorRelatedResource

The error related resource details object.

Name	Type	Description
resourceId	string	The resource ID that's involved in the error.
resourceType	string	The type of the resource that's involved in the error.

ErrorResponse

The error response.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string	ID of the request associated with the error.

ErrorResponseDetails

The error response details.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
relatedResource	ErrorRelatedResource	The error related resource details.

KeyCredentials

Credentials for Key CredentialType.

Name	Type	Description
credentialType	string: Key	The credential type of the connection.
key	string	The key.

ListConnectionDetails

The connection details output for list operations.

Name	Type	Description
path	string	The path of the connection.
type	string	The type of the connection.

ListCredentialDetails

The credential details returned when fetching a connection.

Name	Type	Description
connectionEncryption	ConnectionEncryption	The connection encryption setting that is used during the test connection.
credentialType	CredentialType	The credential type of the connection.
singleSignOnType	SingleSignOnType	The single sign-on type of the connection.
skipTestConnection	boolean	Whether the connection should skip the test connection during creation and update. True - Skip the test connection, False - Do not skip the test connection.

OnPremisesCredentialEntry

A gateway ID and its encrypted serialized credentials.

Name	Type	Description
encryptedCredentials	string	The encrypted serialized .json of the list of name value pairs. Name is a credential name and value is a credential value. Encryption is performed using the Rivest-Shamir-Adleman (RSA) encryption algorithm with the on-premises gateway member's public key.
gatewayId	string	The object ID of the gateway.

OnPremisesGatewayCredentials

Credentials for authenticating through an on-premises gateway.

Name	Type	Description
credentialType	CredentialType	The credential type of the connection.
values	OnPremisesCredentialEntry[]	The credential payload to send to the on-premises gateway.

PrivacyLevel

The privacy level setting of the connection. Additional privacy levels may be added over time.

Name	Type	Description
None	string	No privacy level setting is configured.
Organizational	string	Connections set to organizational can fold in to private and other organizational connections. They can't fold in to public connections. Visibility is set to a trusted group.
Private	string	Connections set to private contain sensitive or confidential information. Visibility can be restricted to authorized users. Data from a private connection won't fold in to other connections, including other private connections.
Public	string	Files, internet connections, and workbook data can be set to public. Data can fold in to other connections. Visibility is available to everyone.

ServicePrincipalCredentials

Credentials for ServicePrincipal CredentialType.

Name	Type	Description
credentialType	string: ServicePrincipal	The credential type of the connection.
servicePrincipalClientId	string	The client ID of the service principal.
servicePrincipalSecret	string	The secret of the service principal.
tenantId	string	The tenant ID of the service principal.

SharedAccessSignatureCredentials

Credentials for SharedAccessSignature CredentialType.

Name	Type	Description
credentialType	string: SharedAccessSignature	The credential type of the connection.
token	string	The token.

SingleSignOnType

The single sign-on type of the connection. Additional single sign on types may be added over time.

Name	Type	Description
Kerberos	string	Connection uses Kerberos single sign-on to connect.
KerberosDirectQueryAndRefresh	string	Connection uses Kerberos DirectQuery and Refresh single sign-on to connect.
MicrosoftEntraID	string	Connection uses Microsoft Entra ID single sign-on to connect.
None	string	Connection does not use single sign-on to connect.
SecurityAssertionMarkupLanguage	string	Connection uses Security Assertion Markup Language (SAML) single sign-on to connect.

WindowsCredentials

Credentials for Windows CredentialType.

Name	Type	Description
credentialType	string: Windows	The credential type of the connection.
password	string	The password.
username	string	The username.

WindowsWithoutImpersonationCredentials

Credentials for WindowsWithoutImpersonation CredentialType.

Name	Type	Description
credentialType	string: WindowsWithoutImpersonation	The credential type of the connection.

WorkspaceIdentityCredentials

Credentials for WorkspaceIdentity CredentialType.

Name	Type	Description
credentialType	string: WorkspaceIdentity	The credential type of the connection.

Share via

Connections - Create Connection

Permissions

Required Delegated Scopes

Microsoft Entra supported identities

Interface

Request Body

CreateCloudConnectionRequest

CreateOnPremisesConnectionRequest

CreateVirtualNetworkGatewayConnectionRequest

Responses

Examples

Cloud example

Sample request

Sample response

Virtual network gateway example

Sample request

Sample response

Definitions

AnonymousCredentials

BasicCredentials

Connection

ConnectionDetailsBooleanParameter

ConnectionDetailsDateParameter

ConnectionDetailsDateTimeParameter

ConnectionDetailsDateTimeZoneParameter

ConnectionDetailsDurationParameter

ConnectionDetailsNumberParameter

ConnectionDetailsTextParameter

ConnectionDetailsTimeParameter

ConnectionEncryption

ConnectivityType

CreateCloudConnectionRequest

CreateConnectionDetails

CreateCredentialDetails

CreateOnPremisesConnectionRequest

CreateOnPremisesCredentialDetails

CreateVirtualNetworkGatewayConnectionRequest

CredentialType

DataType

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

KeyCredentials

ListConnectionDetails

ListCredentialDetails

OnPremisesCredentialEntry

OnPremisesGatewayCredentials

PrivacyLevel

ServicePrincipalCredentials

SharedAccessSignatureCredentials

SingleSignOnType

WindowsCredentials

WindowsWithoutImpersonationCredentials

WorkspaceIdentityCredentials

Additional resources