Coming soon:
Tableau Cloud Manager (TCM) REST API methods are scheduled for release in fall 2024. Site administrators will receive an email two weeks before TCM becomes available.

Authentication


Before you can perform any activities in Tableau Cloud Manager (TCM), you need to authenticate to TCM. Authenticating to Tableau Cloud Manager REST API has different requirements than authenticating to Tableau Cloud Manager.

About authenticating to Tableau Cloud Manager REST API

To authenticate, or sign in, to Tableau Cloud Manager REST API, you must be a cloud administrator, and use a personal access tokens (PAT) to acquire a TCM credentials token. This TCM credentials token is required for any subsequent API requests that you make. You can use the Authentication Methods to sign in to the Tableau Cloud Manager REST API.

For more information, see Sign in to Tableau Cloud Manager REST API below.

About authenticating to Tableau Cloud Manager

To authenticate, or sign in, to the TCM UI, you must be a cloud administrator and one of the following authentication types must be enabled for the tenant:

Note: If SSO is enabled to authenticate users, we recommend that there’s at least one cloud administrator that uses “Tableau with MFA” authentication to ensure uninterrupted access to TCM.

For more information, see Set up TCM authentication for users below.

Sign in to Tableau Cloud Manager REST API

To sign in to Tableau Cloud Manager REST API, you need to generate a personal access token (PAT) through the TCM UI first. After you create the PAT, you’ll use it in the Sign In method request body.

About personal access tokens

PATs are long-lived access tokens. PATs validate that cloud administrators are allowed to sign in to Tableau Cloud Manager REST API. PATs offer the following advantages:

Notes:

For more information about PATs, see the Personal Access Tokens for Tableau Cloud Manager topic in the Tableau Cloud Help.

Step 1: Create a personal access token

When signing in to the Tableau Cloud REST API for the first time, you must generate a PAT in the TSM UI.

  1. Sign in to Tableau Cloud Manager as a cloud administrator.
  2. Navigate to your account drop-down and select My Account Settings.
  3. In the Personal Access Tokens section, do the following:
    • 3.1. Click the Create Token button.
    • 3.2. Enter a token name.
    • 3.3. Optionally, set the token expiration.
    • 3.4. Click Create.
    • 3.5. Click the Copy Secret button to use in your Sign In request. Make sure you store the token secret in a safe location. The token secret is only shown once and won’t be accessible after the dialog box is closed.

Step 2: Make a sign in request with the PAT

The following section describes the different components required to sign in to the Tableau Cloud Manager REST API using the Sign In method.

URI

To call the Tableau Cloud REST API, first make a request using the Sign In method to generate a TCM credentials token like in the example below.

POST https://mytenant.gateway.manage.online.tableau.com/api/v1/pat/login

Request body

Sign In request body must contain the PAT secret like the example below.

{
	 "token":  "JKGpaIjBQaS1vlXIIt9g+A==:-jeD0dkAWu-mwZQPgRf3NvgHQBUZ7atQsPxh911YmPU"
}

Response body

The Sign In request produces the following response body, which includes the TCM credentials token, sessionToken, like in the example below.

{
	"sessionToken": "+iUzQx+s:E9T43sqund-xDGle-9trR7WPLkqCkT_7zks3_dVsV0By_Jji",
	"userId": "306982a2-4bb0-b858-b82eeI24b857",
	"tenantId": "56978815-59b6-4a61-b9e8-ede126e23bab",
	"sessionExpiration": "2024-0706T84:53:13.688541Z"
}

After the TCM credentials token is generated, add it to the header, x-tableau-session-token, for all subsequent Tableau Cloud Manager REST API requests.

+iUzQx+s:E9T43sqund-xDGle-9trR7WPLkqCkT_7zks3_dVsV0By_Jji

Step 3: Include the x-tableau-session-token header in subsequent requests

After the TCM credentials token, sessionToken, is generated, add the TCM credentials token value to the header, x-tableau-session-token, for all subsequent Tableau Cloud Manager REST API requests.

Header

x-tableau-session-token:+iUzQx+s:E9T43sqund-xDGle-9trR7WPLkqCkT_7zks3_dVsV0By_Jji

The TCM credentials token is short-lived. It expires after 4 hours or when the session is idle for 30 continuous minutes with no requests. When the TCM credentials token expires, you need to sign in to Tableau Cloud Manager REST API again to get a new TCM credentials token.

Set up TCM authentication for users

Using the Tableau Cloud Manager REST API, you can configure authentication to Tableau Cloud Manager (TCM) and assign the authentication type to TCM users.

Note: To use Tableau with MFA authentication, skip Step 1: Configure authentication and go directly to Step 2: Assign authentication to users below.

Step 1: Configure authentication

After you make the sign-in request, you can configure Google or Salesforce authentication using the Create or update OIDC configuration method.

The example below sets up Salesforce authentication for the tenant.

URI

PUT https://mytenant.gateway.manage.online.tableau.com/api/v1/resources/123e4567-e89b-12d3-a456-426614174000/oidcconfiguration

Request body

{
  "enabled": true,
  "knownProviderAlias": "Salesforce",
  "salesforceDomain": "login.salesforce.com"
}

Step 2: Assign authentication to users

After the authentication type has been configured for the tenant, assign TCM users to use that authentication type.

Assign SSO authentication

Using the Add tenant user method, set the idp value to OpenID. In this example, Salesforce authentication is assigned to the new TCM user because Salesforce is the authentication type configured for the tenant, which is specified by the knownProviderAlias attribute in Step 1: Configure authentication above.

URI

POST https://mytenant.gateway.manage.online.tableau.com/api/v1/tenants/f97df110-f4de-492e-8849-4a6af68026b0/users

Request body

{
  "linkRoles": [
   {
	"linkID": "ce9cad81-cd67-43fb-b952-2441d7b5a751",
	"linkRole": "LINK_ADMIN",
	"idp": "OpenID"
   }
  ]		
}

Assign Tableau with MFA authentication

Using the Add tenant user method, set the idp value to TabIDWithMFA.

URI

POST https://mytenant.gateway.manage.online.tableau.com/api/v1/tenants/f97df110-f4de-492e-8849-4a6af68026b0/users

Request body

{
  "linkRoles": [
   {
	"linkID": "ce9cad81-cd67-43fb-b952-2441d7b5a751",
	"linkRole": "LINK_ADMIN",
	"idp": "TabIDWithMFA"
   }
  ]		
}