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:
- Create a connected app
- Generate a valid JWT—at runtime your custom application will generate a valid JWT, configured with the scopes you have included
- 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)
-
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:
- For other REST API capabilities not listed in the table below, you can use other authorization mechanisms to access the methods. For more information, see Authentication Methods(Link opens in a new window) in the Tableau REST API Help.
- For scopes supported by the Embedding API v3, see Configure Tableau Connected Apps to Enable SSO for Embedded Content
| 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 |