Gateways - Update Datasource

Reference

Service:: Power BI REST APIs

API Version:: v1.0

Updates the credentials of the specified data source from the specified gateway.

On Premises data source credentials must be encrypted, as described in the On-premise encrypted credentials example.

See the Patch Datasource Credentials PowerShell script for an example of using this API, this script uses the PowerShell script mentioned in the note below for encrypting the credentials.

Note

To encrypt credentials, see Configure credentials programmatically for Power BI and review the EncryptCredentials .NET Core, Java, Python and PowerShell examples.
Windows credentials before encryption look like the credentials in the credentials of Basic credentials example.

When changing from single sign-on to other credential types, such as Basic or OAuth2, set the parameter useEndUserOAuth2Credentials to false as described in the Basic credentials example.

OAuth 2.0 credentials are valid as long as the provided token is valid. When using the OAuth 2.0 credential type, do the following:

Set the OAuth 2.0 token audience correctly, according to the data source type.
Send the OAuth 2.0 token in the payload as shown in the OAuth 2.0 credentials example.
If you're using Extension data sources, don't set useCallerAADIdentity to true.

Permissions

With on-premises gateways, the user must have gateway admin permissions.
With cloud data sources, user must be the data source owner. Use Datasets - Take Over API to transfer ownership over the specified dataset or Paginated reports - Take Over API to transfer ownership of the data sources over the specified paginated report.
This API call can be called by a service principal profile. For more information see: Service principal profiles in Power BI Embedded.

Required Scope

Dataset.ReadWrite.All

Limitations

When setting OAuth credentials, a refresh token isn't incorporated as it is when setting credentials through the UI in Power BI service. Therefore, credentials can only be used for one hour.
Virtual network (VNet) gateways aren't supported.
SAS Token credentials are supported only with AzureBlobStorage and AzureDataLakeStorage.

PATCH https://api.powerbi.com/v1.0/myorg/gateways/{gatewayId}/datasources/{datasourceId}

URI Parameters

Name	In	Required	Type	Description
datasourceId	path	True	string uuid	The data source ID
gatewayId	path	True	string uuid	The gateway ID. When using a gateway cluster, the gateway ID refers to the primary (first) gateway in the cluster. In such cases, gateway ID is similar to gateway cluster ID.

Request Body

Name	Required	Type	Description
credentialDetails	True	CredentialDetails	The credential details

Responses

Name	Type	Description
200 OK		OK

Examples

Anonymous credentials example

Basic credentials example

Key credentials example

OAuth 2.0 credentials example

On-premise encrypted credentials example

SAS Token credentials example

Anonymous credentials example

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/gateways/1f69e798-5852-4fdd-ab01-33bb14b6e934/datasources/252b9de8-d915-4788-aaeb-ec8c2395f970

Request Body

{
  "credentialDetails": {
    "credentialType": "Anonymous",
    "credentials": "{\"credentialData\":\"\"}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

Status code:: 200

Basic credentials example

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/gateways/1f69e798-5852-4fdd-ab01-33bb14b6e934/datasources/252b9de8-d915-4788-aaeb-ec8c2395f970

Request Body

{
  "credentialDetails": {
    "credentialType": "Basic",
    "credentials": "{\"credentialData\":[{\"name\":\"username\", \"value\":\"john\"},{\"name\":\"password\", \"value\":\"*****\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None",
    "useEndUserOAuth2Credentials": "False"
  }
}

Sample response

Status code:: 200

Key credentials example

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/gateways/1f69e798-5852-4fdd-ab01-33bb14b6e934/datasources/252b9de8-d915-4788-aaeb-ec8c2395f970

Request Body

{
  "credentialDetails": {
    "credentialType": "Key",
    "credentials": "{\"credentialData\":[{\"name\":\"key\", \"value\":\"ec....LA=\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

Status code:: 200

OAuth 2.0 credentials example

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/gateways/1f69e798-5852-4fdd-ab01-33bb14b6e934/datasources/252b9de8-d915-4788-aaeb-ec8c2395f970

Request Body

{
  "credentialDetails": {
    "credentialType": "OAuth2",
    "credentials": "{\"credentialData\":[{\"name\":\"accessToken\", \"value\":\"eyJ0....fwtQ\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

Status code:: 200

On-premise encrypted credentials example

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/gateways/1f69e798-5852-4fdd-ab01-33bb14b6e934/datasources/252b9de8-d915-4788-aaeb-ec8c2395f970

Request Body

{
  "credentialDetails": {
    "credentialType": "Windows",
    "credentials": "AB....EF==",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "RSA-OAEP",
    "privacyLevel": "None"
  }
}

Sample response

Status code:: 200

SAS Token credentials example

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/gateways/1f69e798-5852-4fdd-ab01-33bb14b6e934/datasources/252b9de8-d915-4788-aaeb-ec8c2395f970

Request Body

{
  "credentialDetails": {
    "credentialType": "SAS",
    "credentials": "{\"credentialData\":[{\"name\":\"token\", \"value\":\"sp=rl&st=2023-01-16T09:37:25Z&se=2023...J0%2F0YVkjKxPtEwsyn\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

Status code:: 200

Definitions

Name	Description
CredentialDetails	The credential details
credentialType	The type of data source credential
encryptedConnection	Whether to encrypt the data source connection. The API call will fail if you select encryption and Power BI is unable to establish an encrypted connection with the data source.
encryptionAlgorithm	The encryption algorithm. For a cloud data source, specify `None`. For an on-premises data source, specify `RSA-OAEP` and use the gateway public key to encrypt the credentials.
privacyLevel	The privacy level, which is relevant when combining data from multiple sources.
UpdateDatasourceRequest	An update data source to gateway request

CredentialDetails

The credential details

Name	Type	Description
credentialType	credentialType	The credential type
credentials	string	The credentials, which depend on the 'credentialType' value. For more information, see Update Datasource examples.
encryptedConnection	encryptedConnection	Whether to encrypt the data source connection. The API call will fail if you select encryption and Power BI is unable to establish an encrypted connection with the data source.
encryptionAlgorithm	encryptionAlgorithm	The encryption algorithm. For a cloud data source, specify `None`. For an on-premises data source, specify `RSA-OAEP` and use the gateway public key to encrypt the credentials.
privacyLevel	privacyLevel	The privacy level, which is relevant when combining data from multiple sources.
useCallerAADIdentity	boolean	Whether the Azure AD identity (OAuth 2.0 credentials) of the API caller (which must be the data source owner) will be used to configure data source credentials (the owner OAuth access token). Typically, you would either use this flag or `useEndUserOAuth2Credentials`.
useEndUserOAuth2Credentials	boolean	Whether the end-user Azure AD identity (OAuth 2.0 credentials) is used when connecting to the data source in DirectQuery mode. Use with data sources that support single sign-on (SSO). Typically, you would either use this flag or `useCallerAADIdentity`.

credentialType

The type of data source credential

Name	Type	Description
Anonymous	string
Basic	string
Key	string
OAuth2	string
SAS	string
Windows	string

encryptedConnection

Whether to encrypt the data source connection. The API call will fail if you select encryption and Power BI is unable to establish an encrypted connection with the data source.

Name	Type	Description
Encrypted	string
NotEncrypted	string

encryptionAlgorithm

The encryption algorithm. For a cloud data source, specify None. For an on-premises data source, specify RSA-OAEP and use the gateway public key to encrypt the credentials.

Name	Type	Description
None	string
RSA-OAEP	string

privacyLevel

The privacy level, which is relevant when combining data from multiple sources.

Name	Type	Description
None	string
Organizational	string
Private	string
Public	string

UpdateDatasourceRequest

An update data source to gateway request

Name	Type	Description
credentialDetails	CredentialDetails	The credential details

Share via

Gateways - Update Datasource

Permissions

Required Scope

Limitations

URI Parameters

Request Body

Responses

Examples

Anonymous credentials example

Sample request

Sample response

Basic credentials example

Sample request

Sample response

Key credentials example

Sample request

Sample response

OAuth 2.0 credentials example

Sample request

Sample response

On-premise encrypted credentials example

Sample request

Sample response

SAS Token credentials example

Sample request

Sample response

Definitions

CredentialDetails

credentialType

encryptedConnection

encryptionAlgorithm

privacyLevel

UpdateDatasourceRequest

Additional resources