Beginning in June 2022 (Tableau Online only), using Tableau connected apps, you can programmatically call and access the Tableau REST API through your custom application on behalf of Tableau Online users. Access to the REST API is enabled by a JSON Web Token (JWT) defined as part of the initial Sign In request. The JWT must contain scopes that define the REST API methods that are available to your custom application and its users through the connected app.

Authorize access to the REST API using connected apps to:

  • Enhance efficiency—using a JWT as a bearer token enables a simplified impersonation with one request to the Sign In endpoint instead of two requests
  • Extend and automate complex Tableau integrations and backend queries—such as dynamic content retrieval and advanced filtering

Scope types

Connected apps use scopes that grant access to actions on content or administrative tasks through the REST API methods that support JWT authorization (below). A scope is a colon-separated string that starts with the namespace tableau, followed by the Tableau resource that access is being granted to, such as datasources, and ends with the action that is allowed on the resource, such as update.

The actions a scope can take include:

  • create
  • read
  • run
  • update
  • download
  • delete

For example, a scope that allows your custom application to call the Update Data Source(Link opens in a new window) method looks like:

tableau:datasources:update

Summary of how to authorize REST API access

The following list summarizes the steps to request access to the REST API through a JWT:

  1. Create a connected app
  2. Generate a valid JWT—at runtime your custom application will generate a valid JWT, configured with the scopes you have included
  3. Make a Sign In(Link opens in a new window) request—your custom application will make a Sign In request using the JWT to return a Tableau access token and site ID (LUID)
  4. Use the Tableau access token in subsequent requests—in subsequent REST API calls, use 1) the Tableau access token as the X-Tableau-Auth(Link opens in a new window) header value and 2) the site ID (LUID) in the request URI

Example

For example, suppose you create a connected app using direct trust. Using direct trust, your custom application that calls the REST API generates a valid JWT using the client ID and client secret generated by the connected app.

Scopes in the JWT

To successfully authorize access to the REST API, the JWT must also contain the scopes that define the REST API capabilities. For example, to enable various data source-related methods, you might include the following scopes in the JWT:

"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"

Note: Scope values must be passed as a list type.

Sign In Request URI

To make a call to the REST API, your custom application must first make a Sign In request to generate a Tableau access token.

                    POST https://us-west-2b.online.tableau.com/api/3.16/auth/signin
                

Request body

To authorize REST API access using a JWT, the Sign In request body must contain the valid JWT like the example below.

                    <tsRequest>
   <credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
	<site contentUrl="mycodotcom"/>
   </credentials>
</tsRequest>

                

Response body

The Sign In request produces the following response body, which includes the Tableau access token.

                    <tsResponse>
   <credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
	<site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
	<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
   </credentials>
</tsResponse>

                

After the Tableau access token is generated, add the Tableau access token to the header of all subsequent REST API requests.

Header

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

All subsequent REST API requests using the Tableau access token are then bounded by the scopes in the JWT.

REST API methods that support JWT authorization

The following scopes can be associated with the connected app to define access and methods your custom application can have to the REST API(Link opens in a new window) on users' behalf.

Notes:

Method Scope Description
No scope (No scope) When no scopes are defined in the JWT, access to the REST API is denied

Data sources

   
Publish data source tableau:datasources:create Publish a data source to a site or append data to an existing published data source
Query data source tableau:content:read Get information about a published data source

Query data sources

tableau:content:read Get information about all published data source on a site
Query data source connections tableau:content:read Get server address, port, user name, or password information about a published data source
Update data source tableau:datasources:update Update owner, project or certification status of the data source
Update data source connection tableau:datasources:update Update server address, port, user name, or password of the data source connection
Update data source now tableau:tasks:run Run extract refresh

Flows

   
Publish flow tableau:flows:create Publish a flow

Metrics

   
Get metric tableau:content:read Get a metric
Delete metric tableau:metrics:delete Delete a metric
List metrics tableau:content:read Get list of metrics for a site
Query metrics data tableau:metrics:download Get underlying data of a metric in comma-separated value (.csv) format
Update metric tableau:metrics:update Update owner, project, suspend status, and name of the metric

Views

   
Get view tableau:content:read Get details about a view
Get view by path tableau:content:read Get details for all views on a site using the specified name
Query view data tableau:views:download Get a view rendered in comma-separated value (.csv) format
Query view PDF tableau:views:download Get a view as a PDF (.pdf) file
Query view image tableau:views:download Get a view as an image (.png) file
Query views for site tableau:content:read Get all views for a site
Query view preview image tableau:views:download Get the thumbnail image (.png) of the view

Workbooks

   
Publish workbook tableau:workbooks:create Publish a workbook (.twb or .twbx)
Query workbook tableau:content:read Get a specified workbook and its details
Query workbook for site tableau:content:read Get a list of workbooks published to a site
Query workbook preview image tableau:workbooks:download Get the thumbnail image (.png) of the workbook
Update workbook tableau:workbooks:update Modify an existing workbook
Update workbook connection tableau:workbooks:update Update the connection information
Update workbook now tableau:tasks:run Initiate a workbook refresh outside of a scheduled task

Publish

   
Append to file upload tableau:file_uploads:create Upload a block of data and append it to the data that is already uploaded - to be used after an upload has been initiated using the "initiate file upload" method
Initiate file upload tableau:file_uploads:create Initiate the upload process of a file

Download

   
Download data source tableau:datasources:download Download the data source (.tdsx)
Download view crosstab Excel tableau:views:download Download an Excel (.xlsx) file containing crosstab data from the view
Download workbook tableau:workbooks:download Download a workbook (.twb or .twbx)
Download workbook revision tableau:workbooks:download Download a specific version of the workbook (.twb or .twbx)
Download workbook PDF tableau:views:download Download a PDF (.pdf) file containing images of the sheets in the workbook
Download workbook Power Point tableau:views:download Download a Power Point (.pptx) file containing slides of the sheets in the workbook

Users

   
Add user to group tableau:groups:update Add a user to a group
Add user to site tableau:users:create Add a user and assign the user to a site
Get users in group tableau:groups:read Get a list of users in a group
Get users on site tableau:users:read Get all users on a site
Query user on site tableau:users:read Get a user on a site
Remove users from group tableau:groups:update Remove a user from a group
Remove user from site tableau:users:delete Remove the user from a site
Update user tableau:users:update Update information about a user

Groups

   
Create group tableau:groups:create Create a group
Delete group tableau:groups:delete Delete a group
Get groups for user tableau:users:read Get a list of groups that a user belongs to
Query groups tableau:groups:read Get a list of groups on a site
Update group tableau:groups:update Update a group

Projects

   
Create project tableau:projects:create Create a project
Delete project tableau:projects:delete Delete a project
Query project tableau:content:read Get a list of projects
Update project tableau:projects:update Update the name, description, or project hierarchy of the project

Permissions

   
Add data source permissions tableau:permissions:update Add permissions to a data source for a Tableau Server user or group
Add default permissions tableau:permissions:update Add default permission capabilities to a user or group, for metric, flow, workbook, data source, data role, or lens resources in a project
Add project permissions tableau:permissions:update Add permissions to a project for a user or group
Add view permissions tableau:permissions:update Add permissions to a view for a user or group
Add workbook permissions tableau:permissions:update Add permissions to a specified workbook for a user or group
Delete data source permissions tableau:permissions:delete Delete default permission capabilities of a user or group, for metric, flow, workbook, data source, data role, or lens resources in a project
Delete default permissions tableau:permissions:delete Delete default permission capabilities of a user or group, for metric, flow, workbook, data source, data role, or lens resources in a project
Delete project permissions tableau:permissions:delete Delete the project permission for a user or group
Delete view permissions tableau:permissions:delete Delete the view permission for a user or group
Delete workbook permissions tableau:permissions:delete Delete the workbook permission for a user or group
Query data source permissions tableau:permissions:read Get a list of permissions for the data source
Query default permissions tableau:permissions:read Get default permission capabilities of users and groups for metric, flow, workbook, data source, data role, or lens resources in a project
Query project permissions tableau:permissions:read Get a list of permissions for the project
Query view permissions tableau:permissions:read Get a list of permissions for the view
Query workbook permissions tableau:permissions:read Get a list of permissions for the workbook

Site

   
Get recently viewed site tableau:content:read Get views and workbooks details on the most recently created, updated, or accessed by the signed in user
Query site tableau:content:read Get information about a site
Query views for site tableau:content:read List all views on a site
Update site tableau:sites:update Update a site
Thanks for your feedback!