Gateways - Update Datasource

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

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

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
{
  "credentialDetails": {
    "credentialType": "Anonymous",
    "credentials": "{\"credentialData\":\"\"}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

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
{
  "credentialDetails": {
    "credentialType": "Basic",
    "credentials": "{\"credentialData\":[{\"name\":\"username\", \"value\":\"john\"},{\"name\":\"password\", \"value\":\"*****\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None",
    "useEndUserOAuth2Credentials": "False"
  }
}

Sample response

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
{
  "credentialDetails": {
    "credentialType": "Key",
    "credentials": "{\"credentialData\":[{\"name\":\"key\", \"value\":\"ec....LA=\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

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
{
  "credentialDetails": {
    "credentialType": "OAuth2",
    "credentials": "{\"credentialData\":[{\"name\":\"accessToken\", \"value\":\"eyJ0....fwtQ\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}

Sample response

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
{
  "credentialDetails": {
    "credentialType": "Windows",
    "credentials": "AB....EF==",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "RSA-OAEP",
    "privacyLevel": "None"
  }
}

Sample response

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
{
  "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

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