Connections - Create Connection

Service:: Core

API Version:: v1

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

Permissions

If creating a gateway connection, the caller must have permissions for the gateway..
Service Principals must have permission granted by Fabric administrator. For more information see: Service principals can create workspaces, connections, and deployment pipelines.

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
CreateStreamingVirtualNetworkGatewayConnectionRequest	Creates a connection that connects through a streaming virtual network data gateway.
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.
allowConnectionUsageInGateway		boolean	Allow this connection to be utilized with either on-premises data gateways or VNet data gateways.
allowUsageInUserControlledCode		boolean	Allow this connection to be used with items that allow user-controlled code such as Notebook
privacyLevel		PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

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 (uuid)	The object ID of the primary gateway of the on-premises gateway that the connection is created under.
privacyLevel		PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

CreateStreamingVirtualNetworkGatewayConnectionRequest

Creates a connection that connects through a streaming virtual network data gateway.

Name	Required	Type	Description
connectionDetails	True	CreateConnectionDetails	The connection details of the connection.
connectivityType	True	string: StreamingVirtualNetworkGateway	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 (uuid)	The object ID of the streaming virtual network gateway that the connection is created under.
privacyLevel		PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

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 (uuid)	The object ID of the virtual network gateway that the connection is created under.
privacyLevel		PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

Responses

Name Type Description

201 Created

Name	Type	Description
201 Created	Connection: ShareableCloudConnection PersonalCloudConnection OnPremisesGatewayConnection OnPremisesGatewayPersonalConnection VirtualNetworkGatewayConnection StreamingVirtualNetworkGatewayConnection	Created. The operation was successful.
429 Too Many Requests	ErrorResponse	The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests. Headers Retry-After: integer
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.

Connection:

ShareableCloudConnection
PersonalCloudConnection
OnPremisesGatewayConnection
OnPremisesGatewayPersonalConnection
VirtualNetworkGatewayConnection
StreamingVirtualNetworkGatewayConnection

Created. The operation was successful.

429 Too Many Requests

ErrorResponse

The service rate limit was exceeded. The server returns a Retry-After header indicating, in seconds, how long the client must wait before sending additional requests.

Headers

Retry-After: integer

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

Cloud example with KeyPair credentials

On-premises gateway example

Streaming virtual network gateway 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",
      "passwordReference": {
        "connectionId": "4399ab2c-7551-4c0e-8aa7-18fc2f217626",
        "secretName": "some-secret"
      }
    }
  },
  "allowUsageInUserControlledCode": true
}

Sample response

Status code:: 201

{
  "allowUsageInUserControlledCode": true,
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "gatewayId": "8f72eea3-d989-4a5a-aeed-02b3aaa2ddd0",
  "displayName": "ContosoCloudConnection",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  },
  "connectionRecency": {
    "createdDateTime": "2023-05-23T16:22:20Z"
  },
  "myRole": "Owner"
}

Cloud example with KeyPair credentials

Sample request

HTTP

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

{
  "connectivityType": "ShareableCloud",
  "displayName": "SnowflakeCloudConnection",
  "connectionDetails": {
    "type": "SQL",
    "creationMethod": "SQL",
    "parameters": [
      {
        "dataType": "Text",
        "name": "server",
        "value": "contoso.database.windows.net"
      },
      {
        "dataType": "Text",
        "name": "warehouse",
        "value": "snowflake-warehouse"
      }
    ]
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false,
    "credentials": {
      "credentialType": "KeyPair",
      "identifier": "admin",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\\nMIIEvQIBADANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQ...\\n-----END ENCRYPTED PRIVATE KEY-----",
      "passphrase": "********"
    }
  }
}

Sample response

Status code:: 201

{
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "gatewayId": "8f72eea3-d989-4a5a-aeed-02b3aaa2ddd0",
  "displayName": "ContosoCloudConnection",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;snowflake-warehouse"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "KeyPair",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  },
  "connectionRecency": {
    "createdDateTime": "2023-05-23T16:22:20Z"
  },
  "myRole": "Owner"
}

On-premises gateway example

Sample request

HTTP

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

{
  "connectivityType": "OnPremisesGateway",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "displayName": "ContosoOnPremisesConnection",
  "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": "Windows",
      "values": [
        {
          "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
          "encryptedCredentials": "************************************"
        },
        {
          "gatewayId": "55226bab-5024-4b72-9716-6dc8ef3a97fe",
          "encryptedCredentials": "************************************"
        }
      ]
    }
  }
}

Sample response

Status code:: 201

{
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "displayName": "ContosoOnPremisesConnection",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "connectivityType": "OnPremisesGateway",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  },
  "connectionRecency": {
    "createdDateTime": "2023-05-23T16:22:20Z"
  },
  "myRole": "Owner"
}

Streaming virtual network gateway example

Sample request

HTTP

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

{
  "connectivityType": "StreamingVirtualNetworkGateway",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "displayName": "ContosoStreamingVirtualNetworkGatewayConnection",
  "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": "ContosoStreamingVirtualNetworkGatewayConnection",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "connectivityType": "StreamingVirtualNetworkGateway",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "Encrypted",
    "skipTestConnection": false
  },
  "myRole": "Owner"
}

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
  },
  "connectionRecency": {
    "createdDateTime": "2023-05-23T16:22:20Z"
  },
  "myRole": "Owner"
}

Definitions

Name	Description
AnonymousCredentials	Credentials for Anonymous CredentialType.
BasicCredentials	Credentials for Basic CredentialType.
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.
ConnectionRecency	Represents the recency details about the connection.
ConnectionRole	A connection role. Additional connection roles 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.
CreateStreamingVirtualNetworkGatewayConnectionRequest	Creates a connection that connects through a streaming virtual network data gateway.
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.
ErrorParameter	A structured parameter providing additional machine-readable context about an error.
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
KeyCredentials	Credentials for Key CredentialType.
KeyPairCredentials	Credentials for KeyPair CredentialType.
KeyVaultSecretReference	The reference to a secret stored in Azure Key Vault.
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.
OnPremisesGatewayConnection	A connection that connects through on-premises data gateway.
OnPremisesGatewayCredentials	Credentials for authenticating through an on-premises gateway.
OnPremisesGatewayPersonalConnection	A connection that connects through a personal on-premises data gateway.
PersonalCloudConnection	A connection that connects through the cloud and cannot be shared.
PrivacyLevel	The privacy level setting of the connection. Additional privacy levels may be added over time.
ServicePrincipalCredentials	Credentials for ServicePrincipal CredentialType.
ShareableCloudConnection	A connection that connects through the cloud.
SharedAccessSignatureCredentials	Credentials for SharedAccessSignature CredentialType.
SingleSignOnType	The single sign-on type of the connection. Additional single sign on types may be added over time.
StreamingVirtualNetworkGatewayConnection	A connection that connects through a streaming virtual network data gateway.
VirtualNetworkGatewayConnection	A connection that connects through a virtual network data gateway.
WindowsCredentials	Credentials for Windows CredentialType.
WindowsWithoutImpersonationCredentials	Credentials for WindowsWithoutImpersonation CredentialType.
WorkspaceIdentityCredentials	Credentials for WorkspaceIdentity CredentialType.

AnonymousCredentials

Object

Credentials for Anonymous CredentialType.

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

BasicCredentials

Object

Credentials for Basic CredentialType.

Name	Type	Description
credentialType	string: Basic	The credential type of the connection.
password	string	The password. Use password or passwordReference. You can't use both at the same time
passwordReference	KeyVaultSecretReference	The reference to a password stored in Azure Key Vault. Use password or passwordReference. You can't use both at the same time.
username	string	The username.

ConnectionDetailsBooleanParameter

Object

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

Object

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 (date)	The date value using YYYY-MM-DD format.

ConnectionDetailsDateTimeParameter

Object

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 (date-time)	The date time value using YYYY-MM-DDTHH:mm:ss.FFFZ format.

ConnectionDetailsDateTimeZoneParameter

Object

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 (date-time-offset)	The date time zone value using YYYY-MM-DDTHH:mm:ss.FFF±hh:mm format.

ConnectionDetailsDurationParameter

Object

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 (time-span)	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

Object

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

Object

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

Object

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 (time)	The time value using HH:mm:ss.FFFZ format.

ConnectionEncryption

Enumeration

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

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

ConnectionRecency

Object

Represents the recency details about the connection.

Name	Type	Description
createdDateTime	string (date-time)	The timestamp when the connection was created in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
lastBoundDateTime	string (date-time)	The timestamp when the connection was most recently bound to any item in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
lastCredentialUsedDateTime	string (date-time)	The timestamp when the connection credentials were most recently used in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
myLastBoundDateTime	string (date-time)	The timestamp when the connection was most recently bound to any item by the calling user in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
myLastCredentialUsedDateTime	string (date-time)	The timestamp when the connection credentials were most recently used by the calling user in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.

ConnectionRole

Enumeration

A connection role. Additional connection roles may be added over time.

Value	Description
User	Enables user access for the connection.
UserWithReshare	Enables user with resharing access for the connection.
Owner	Enables ownership access for the connection.
PendingOwner	Ownership of the connection is not yet effective; the principal must update the connection credentials (using Update Connection API) to make it effective.

ConnectivityType

Enumeration

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

Value	Description
ShareableCloud	The connection connects through the cloud and can be shared with others.
PersonalCloud	The connection connects through the cloud and cannot be shared with others.
OnPremisesGateway	The connection connects through an on-premises data gateway.
OnPremisesGatewayPersonal	The connection connects through a personal on-premises data gateway.
VirtualNetworkGateway	The connection connects through a virtual network data gateway.
StreamingVirtualNetworkGateway	The connection connects through a streaming virtual network data gateway.
Automatic	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	The connection is not bound

CreateCloudConnectionRequest

Object

Name	Type	Default value	Description
allowConnectionUsageInGateway	boolean		Allow this connection to be utilized with either on-premises data gateways or VNet data gateways.
allowUsageInUserControlledCode	boolean	False	Allow this connection to be used with items that allow user-controlled code such as Notebook
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		(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

CreateConnectionDetails

Object

The connection details input for create operations.

Name	Type	Description
creationMethod	string	The creation method used to create the connection. For a list of creation methods use the ListSupportedConnectionTypes API.
parameters	ConnectionDetailsParameter[]: ConnectionDetailsBooleanParameter[] ConnectionDetailsDateParameter[] ConnectionDetailsDateTimeParameter[] ConnectionDetailsDateTimeZoneParameter[] ConnectionDetailsDurationParameter[] ConnectionDetailsNumberParameter[] ConnectionDetailsTextParameter[] ConnectionDetailsTimeParameter[]	The list of connection parameters. For a list of parameters for each creation method use the ListSupportedConnectionTypes API.
type	string	The type of the connection.

CreateCredentialDetails

Object

The credential details input for creating a connection.

Name	Type	Description
connectionEncryption	ConnectionEncryption	(Optional) The connection encryption setting that is used during the test connection. When no value is passed, the connection is not encrypted.
credentials	Credentials: AnonymousCredentials BasicCredentials KeyCredentials KeyPairCredentials ServicePrincipalCredentials SharedAccessSignatureCredentials WindowsCredentials WindowsWithoutImpersonationCredentials WorkspaceIdentityCredentials	The credentials of the connection.
singleSignOnType	SingleSignOnType	(Optional) The single sign-on type of the connection. When no value is passed, the connection doesn't use single sign-on.
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. When no value is passed, this is set to 'False'.

CreateOnPremisesConnectionRequest

Object

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 (uuid)	The object ID of the primary gateway of the on-premises gateway that the connection is created under.
privacyLevel	PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

CreateOnPremisesCredentialDetails

Object

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

Name	Type	Description
connectionEncryption	ConnectionEncryption	(Optional) The connection encryption setting that is used during the test connection. When no value is passed, the connection is not encrypted.
credentials	OnPremisesGatewayCredentials	The credentials of the connection.
singleSignOnType	SingleSignOnType	(Optional) The single sign-on type of the connection. When no value is passed, the connection doesn't use single sign-on.
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. When no value is passed, this is set to 'False'.

CreateStreamingVirtualNetworkGatewayConnectionRequest

Object

Creates a connection that connects through a streaming virtual network data gateway.

Name	Type	Description
connectionDetails	CreateConnectionDetails	The connection details of the connection.
connectivityType	string: StreamingVirtualNetworkGateway	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 (uuid)	The object ID of the streaming virtual network gateway that the connection is created under.
privacyLevel	PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

CreateVirtualNetworkGatewayConnectionRequest

Object

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 (uuid)	The object ID of the virtual network gateway that the connection is created under.
privacyLevel	PrivacyLevel	(Optional) The privacy level of the connection. When no value is passed, this is set to 'Organizational'.

CredentialType

Enumeration

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

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

DataType

Enumeration

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

Value	Description
Text	Use text as the parameter input value.
Number	Use number as the parameter input value (integer or floating point).
Boolean	Use boolean as the parameter input value. False - the value is false, True - the value is true.
Duration	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).
Date	Use date as the parameter input value, using YYYY-MM-DD format.
DateTime	Use date time as the parameter input value, using YYYY-MM-DDTHH:mm:ss.FFFZ format.
DateTimeZone	Use date time zone as the parameter input value, using YYYY-MM-DDTHH:mm:ss.FFF±hh:mm format.
Time	Use time as the parameter input value, using HH:mm:ss.FFFZ format.

ErrorParameter

Object

A structured parameter providing additional machine-readable context about an error.

Name	Type	Description
message	string	A human-readable description of the parameter's meaning.
name	string	The parameter identifier.
value	string	The parameter value.

ErrorRelatedResource

Object

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

Object

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.
isRetriable	boolean	When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
parameters	ErrorParameter[]	Structured parameters providing additional machine-readable context about the error.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string (uuid)	ID of the request associated with the error.

ErrorResponseDetails

Object

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.
parameters	ErrorParameter[]	Structured parameters providing additional machine-readable context about the error.
relatedResource	ErrorRelatedResource	The error related resource details.

KeyCredentials

Object

Credentials for Key CredentialType.

Name	Type	Description
credentialType	string: Key	The credential type of the connection.
key	string	The key. Use key or keyReference. You can't use both at the same time.
keyReference	KeyVaultSecretReference	The reference to a key stored in Azure Key Vault. Use key or keyReference. You can't use both at the same time.

KeyPairCredentials

Object

Credentials for KeyPair CredentialType.

Name	Type	Description
credentialType	string: KeyPair	The credential type of the connection.
identifier	string	The identifier for the key.
passphrase	string	The passphrase for the private key if the private key is encrypted.
privateKey	string	The private key based on PKCS #8 standard.

KeyVaultSecretReference

Object

The reference to a secret stored in Azure Key Vault.

Name	Type	Description
connectionId	string (uuid)	The connection ID of the Key Vault connection.
secretName	string	The name of the secret in Key Vault.
version	string	The version of the secret in Key Vault.

ListConnectionDetails

Object

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

Object

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

Object

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 (uuid)	The object ID of the gateway.

OnPremisesGatewayConnection

Object

A connection that connects through on-premises data gateway.

Name	Type	Description
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectionRecency	ConnectionRecency	The recency details about the connection.
connectivityType	string: OnPremisesGateway	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string (uuid)	The gateway object ID through which the connection is made. For cloud connections, this is the virtual gateway ID.
id	string (uuid)	The object ID of the connection.
myRole	ConnectionRole	The calling principal's effective role on the connection. When the principal is part of multiple security groups with different roles, the highest role is returned. If the principal has no role on the connection, this property is not returned.
privacyLevel	PrivacyLevel	The privacy level of the connection.

OnPremisesGatewayCredentials

Object

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.

OnPremisesGatewayPersonalConnection

Object

A connection that connects through a personal on-premises data gateway.

Name	Type	Description
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectionRecency	ConnectionRecency	The recency details about the connection.
connectivityType	string: OnPremisesGatewayPersonal	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string (uuid)	The gateway object ID through which the connection is made. For cloud connections, this is the virtual gateway ID.
id	string (uuid)	The object ID of the connection.
myRole	ConnectionRole	The calling principal's effective role on the connection. When the principal is part of multiple security groups with different roles, the highest role is returned. If the principal has no role on the connection, this property is not returned.
privacyLevel	PrivacyLevel	The privacy level of the connection.

PersonalCloudConnection

Object

A connection that connects through the cloud and cannot be shared.

Name	Type	Description
allowConnectionUsageInGateway	boolean	Allow this connection to be utilized with either on-premises data gateways or VNet data gateways.
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectionRecency	ConnectionRecency	The recency details about the connection.
connectivityType	string: PersonalCloud	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string (uuid)	The gateway object ID through which the connection is made. For cloud connections, this is the virtual gateway ID.
id	string (uuid)	The object ID of the connection.
myRole	ConnectionRole	The calling principal's effective role on the connection. When the principal is part of multiple security groups with different roles, the highest role is returned. If the principal has no role on the connection, this property is not returned.
privacyLevel	PrivacyLevel	The privacy level of the connection.

PrivacyLevel

Enumeration

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

Value	Description
None	No privacy level setting is configured.
Private	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.
Organizational	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.
Public	Files, internet connections, and workbook data can be set to public. Data can fold in to other connections. Visibility is available to everyone.

ServicePrincipalCredentials

Object

Credentials for ServicePrincipal CredentialType.

Name	Type	Description
credentialType	string: ServicePrincipal	The credential type of the connection.
servicePrincipalClientId	string (uuid)	The client ID of the service principal.
servicePrincipalSecret	string	The secret of the service principal. Use servicePrincipalSecret or servicePrincipalSecretReference. You can't use both at the same time.
servicePrincipalSecretReference	KeyVaultSecretReference	The reference to a service principal secret stored in Azure Key Vault. Use servicePrincipalSecret or servicePrincipalSecretReference. You can't use both at the same time.
tenantId	string (uuid)	The tenant ID of the service principal.

ShareableCloudConnection

Object

A connection that connects through the cloud.

Name	Type	Description
allowConnectionUsageInGateway	boolean	Allow this connection to be utilized with either on-premises data gateways or VNet data gateways.
allowUsageInUserControlledCode	boolean	Allow this connection to be used with items that allow user-controlled code such as Notebook.
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectionRecency	ConnectionRecency	The recency details about the connection.
connectivityType	string: ShareableCloud	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string (uuid)	The gateway object ID through which the connection is made. For cloud connections, this is the virtual gateway ID.
id	string (uuid)	The object ID of the connection.
myRole	ConnectionRole	The calling principal's effective role on the connection. When the principal is part of multiple security groups with different roles, the highest role is returned. If the principal has no role on the connection, this property is not returned.
privacyLevel	PrivacyLevel	The privacy level of the connection.

SharedAccessSignatureCredentials

Object

Credentials for SharedAccessSignature CredentialType.

Name	Type	Description
credentialType	string: SharedAccessSignature	The credential type of the connection.
token	string	The token. Use token or tokenReference. You can't use both at the same time.
tokenReference	KeyVaultSecretReference	The reference to a token stored in Azure Key Vault. Use token or tokenReference. You can't use both at the same time.

SingleSignOnType

Enumeration

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

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

StreamingVirtualNetworkGatewayConnection

Object

A connection that connects through a streaming virtual network data gateway.

Name	Type	Description
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectionRecency	ConnectionRecency	The recency details about the connection.
connectivityType	string: StreamingVirtualNetworkGateway	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string (uuid)	The gateway object ID of the connection.
id	string (uuid)	The object ID of the connection.
myRole	ConnectionRole	The calling principal's effective role on the connection. When the principal is part of multiple security groups with different roles, the highest role is returned. If the principal has no role on the connection, this property is not returned.
privacyLevel	PrivacyLevel	The privacy level of the connection.

VirtualNetworkGatewayConnection

Object

A connection that connects through a virtual network data gateway.

Name	Type	Description
connectionDetails	ListConnectionDetails	The connection details of the connection.
connectionRecency	ConnectionRecency	The recency details about the connection.
connectivityType	string: VirtualNetworkGateway	The connectivity type of the connection.
credentialDetails	ListCredentialDetails	The credential details of the connection.
displayName	string	The display name of the connection.
gatewayId	string (uuid)	The gateway object ID through which the connection is made. For cloud connections, this is the virtual gateway ID.
id	string (uuid)	The object ID of the connection.
myRole	ConnectionRole	The calling principal's effective role on the connection. When the principal is part of multiple security groups with different roles, the highest role is returned. If the principal has no role on the connection, this property is not returned.
privacyLevel	PrivacyLevel	The privacy level of the connection.

WindowsCredentials

Object

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

Object

Credentials for WindowsWithoutImpersonation CredentialType.

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

WorkspaceIdentityCredentials

Object

Credentials for WorkspaceIdentity CredentialType.

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