Access Scopes for Connected Apps

Beginning in June 2022, using Tableau connected apps, you can programmatically call and access the Tableau REST API through your custom application on behalf of Tableau Cloud 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 actions

Connected apps use scopes that grant access to content or administrative actions 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 action 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

Scope types

The type of scope you use depends on the content or administrative action that you want to enable. Scopes generally fall into one of the following types: content read, individual, wildcard, and cross-category.

  • Content read scope: The content read scope, tableau:content:read, enables supported GET methods for Tableau content. When you use this scope, you enable actions across REST API categories. More specifically, using this scope you enable GET methods for data sources, metrics, views, workbooks, projects, and sites. Starting in Tableau Cloud October 2023, you also specify this scope in a JWT that will be used to create a credentials token for use with the Metadata API(Link opens in a new window).

    Note: To enable GET methods for administrative actions, like users and groups, you can use their individual scopes.

  • Individual scopes: To enable supported content and administrative actions, you can use their individual scopes. An individual scope is generally associated with a single method and REST API category.

    Examples:

    • To enable publish or update a data source action, you can use the individual tableau:datasources:create or tableau:datasources:update scope, respectively.
    • For administrative actions like add or remove users, you can use the individual tableau:users:create or tableau:users:delete scope, respectively.

    Note: There are some individual scopes that can enable actions across REST API categories. For example, tableau:views:download enables actions in the view data and workbooks REST API categories.

  • Wildcard (*) scopes: For certain scopes, you can replace the action with the wildcard character (*) to enable supported actions within a specific REST API category.

    Examples:

    • You can use the tableau:projects:* wildcard scope to enable the create, delete, update actions in the projects REST API category.
    • You can use the tableau:users:* wildcard scope to enable the get/list, add, delete, update actions in the users REST API category.
    • You can use the tableau:tasks:* wildcard scope to enable the get/list, add, delete, update and run actions of extract and subscriptions REST API categories. In addition, this scope enables update data source (if an extract) and update workbook.
  • Cross-category scopes: In addition to the content read scope, there are a few additional scopes that, if used, enable supported actions across different REST API categories.

    Examples:

    • If using the tableau:tasks:run scope, you enable actions in the data sources and workbooks REST API categories.
    • Again, if using the tableau:views:download scope, you enable actions in the view data and workbook REST API categories.
    • If using permissions scopes like tableau:permissions:update or tableau:permissions:delete, you enable actions in the data sources, workbooks, and projects REST API categories.

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 using one of the following methods:
  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 credentials token and site ID (LUID)
  4. Use the Tableau access token in subsequent requests—in subsequent REST API calls, use 1) the Tableau credentials 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"

Or

"tableau:content:read","tableau:datasources:*","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 credentials 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 credentials 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 credentials 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:

Wildcard (*) scopes

Wildcard scopes use the wildcard character (*) instead of a specific action, to enable multiple supported actions within a specific REST API category. These include:

Scope Methods enabled
tableau:datasources:* Enables create, update, and update connection data source methods.
tableau:metrics:* Enables query, update, and delete metrics actions.
tableau:workbooks:* Enables publish, update, download, and preview image workbook actions.
tableau:groups:* Enables create, query, update, and delete groups actions.
tableau:projects:* Enables create, delete, and update projects methods.
tableau:users:* Enables get/list, add, delete, and update users methods.
tableau:tasks:*

Note: This scope is also cross-category.

Enables get/list, add, delete, update and run methods for extracts and subscription tasks.

Enables update methods for data sources for workbooks.

Cross-category scopes

Cross-category scopes enable multiple supported actions across multiple REST API categories. These include:

Scope Methods enabled
tableau:content:read Enables read/list methods for Tableau content, including data sources, metrics, views, workbooks, projects, and sites.
tableau:tasks:run Enables run methods for data sources, workbooks, and extracts.
tableau:views:download Enables download methods for view data and workbooks.
tableau:tasks:*

Note: This scope is also wildcard.

Enables get/list, add, delete, update and run methods for extracts and subscription tasks.

Enables update methods for data sources for workbooks.

Individual scopes

Method Scope Description
(Methods without scopes) (None) When no scopes are defined in the JWT, access to the REST API is denied.
Sign in (No scope needed) Signs you in as a user on Tableau Cloud.
Sign out (No scope needed) Signs you out of the current session.
(Content read scope) tableau:content:read Enables read/list actions for Tableau content: data sources, metrics, views, workbooks, and projects.

Labels

   
Delete Label tableau:labels:delete Deletes a data label by its LUID.
Delete Labels tableau:labels:delete Deletes the data labels on one or more assets.
Get Label tableau:labels:read Gets a data label by its LUID.
Get Labels tableau:labels:read Displays information about the data labels on one or more assets.
Update Label tableau:labels:update Updates a label by its LUID.
Update Labels tableau:labels:update Creates or updates labels on one or more assets.

Data sources

   
(All tableau:datasources: methods) tableau:datasources:* Enables create data source, update data source, and update data source connection methods.
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.

Pulse

   
Create metric definition tableau:insight_definitions:create Creates a metric definition.
List metric definitions tableau:insight_definitions_metrics:read Lists the metric definitions configured for a site or, optionally, the details and definition for a specific metric.
Delete metric definition tableau:insight_definitions:delete Deletes a metric definition.
Get metric definition tableau:insight_definitions_metrics:read Gets a metric definition and optionally metrics it contains.
Update metric definition tableau:insight_definitions:update Updates a metric definition.
List metrics in definition tableau:insight_definitions_metrics:read Lists the metrics contained in a metric definition
Batch list metric definitions tableau:insight_definitions_metrics:read Gets a batch of metric definitions and metrics available on a site.
Generate current metric value insight bundle tableau:insights:read Generates an bundle with the current aggregated value of the metric.
Generate detail insight bundle tableau:insights:read Generates a detail insight bundle.
Generate springboard insight bundle tableau:insight:read Generates a springboard insight bundle.
Create metric tableau:insight_metrics:create Creates a metric.
Delete metric tableau:insight_metrics:delete Deletes a metric.
Get metric tableau:insight_metrics:read Gets the details of the specified metric.
Update metric tableau:insight_metrics:update Updates a metric.
Batch list metrics tableau:insight_metrics:read Gets a batch of metrics from a definition, specified in a comma delimited list.
Get or create metric tableau:insight_metrics:create Returns the details of a metric in a definition if it exists, or creates a new metric if it does not. Also returns true if a new metric was created, or false if it already existed.
Create subscription tableau:metric_subscriptions:create Creates a subscription to a specified metric for a specified user and/or group.
List subscriptions tableau:metric_subscriptions:read Lists the subscriptions to a specified metric and/or for a specified user.
Delete subscription tableau:metric_subscriptions:delete Deletes a specified subscription from a metric.
Get subscription tableau:metric_subscriptions:read Gets a specified subscription to a metric.
Update subscription tableau:metric_subscriptions:update Updates which metric the subscriptions is for, and/or which users and/or groups are subscribed.
Batch create subscriptions tableau:metric_subscriptions:create Creates multiple subscriptions to a metric for specified users and/or groups.
Batch get subscriptions tableau:metric_subscriptions:read Gets a batch of subscriptions to a metric, specified in a comma delimited list of metric LUIDs.
Batch get subscriber counts tableau:metric_subscriptions:read Gets the number of unique users subscribed to a set of metrics specified in a comma separated list of metric LUIDs.

Extracts

   
(All tableau:tasks: methods) tableau:tasks:* Enables create, delete, get, list, run, and update refresh actions for extracts, subscriptions, update data source (for data sources with extracts), and update workbook methods.
Create Cloud extract refresh task tableau:tasks:create Create an extract refresh for a Tableau Cloud workbook or data source.
Delete extract refresh task tableau:tasks:delete Delete an extract refresh tasks for a Tableau Cloud workbook or data source.
Get extract refresh task tableau:tasks:read Get the details of an extract refresh for a Tableau Cloud workbook or data source.
List extract refresh tasks in site tableau:tasks:read List the extract refreshes tasks configured for in a site.
Run extract refresh task tableau:tasks:run Runs an extract refresh task.
Update Cloud extract refresh task tableau:tasks:update Update an extract refresh for a Tableau Cloud workbook or data source.

Flows

   
Publish flow tableau:flows:create Publish a flow.

Metrics

Retirement of the legacy metrics feature

Tableau's legacy metrics feature was retired in Tableau Cloud in February 2024 and in Tableau Server version 2024.2. In October 2023, Tableau retired the ability to embed legacy metrics in Tableau Cloud and in Tableau Server version 2023.3. With Tableau Pulse, we've developed an improved experience to track metrics and ask questions of your data. For more information, see Create Metrics with Tableau Pulse to learn about the new experience and Create and Troubleshoot Metrics (Retired) for the retired feature.

(All tableau:metrics: methods) tableau:metrics:* Enables query, update, and delete metrics actions.
(All tableau:metrics: methods) tableau:metrics:* Enables query, update, and delete metrics actions.
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.

Subscriptions

   
(All tableau:tasks: methods) tableau:tasks:* Enables create, delete, get, list, run, and update refresh actions for extracts, subscriptions, update data source (for data sources with extracts), and update workbook methods.
Create subscription tableau:tasks:create Create a subscription.
Delete subscription tableau:tasks:delete Delete a subscription.
Get subscription tableau:tasks:read Gets the details of a subscription.
List subscriptions tableau:tasks:read Lists subscriptions in a site.
Update subscription tableau:tasks:update Updates a subscription.

Views

   
Delete custom view tableau:views:update Delete the specified custom view.
Get custom view tableau:content:read Get the details of a specified custom view.
Get custom view image tableau:views:download Download a .png format image file of a specified custom view.
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.
List custom views tableau:content:read Get a list of custom views on a site.
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 views for workbook tableau:content:read Get all views for the specified workbook.
Query view preview image tableau:views:download Get the thumbnail image (.png) of the view.
Update custom view tableau:views:update Change the owner or name of an existing custom view.

Workbooks

   
(All tableau:workbooks: methods) tableau:workbooks:* Enables publish, update, download, and preview image workbook actions.
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 PowerPoint tableau:views:download Download a PowerPoint (.pptx) file containing slides of the sheets in the workbook.

Users

   
(All tableau:users methods) tableau:users:* Enables add, query, update, and remove users actions.
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.

Groups

   
(All tableau:groups: methods) tableau:groups:* Enables create, query, update, and delete groups actions.
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

   
(All tableau:projects: methods) tableau:projects:* Enables create, update, and delete projects actions.
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

   
(All tableau:permissions: methods) tableau:permissions:* Enables add, query, update, delete permissions actions.
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 metrics, workbooks, and data sources.
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

   
(All tableau:sites: methods) tableau:sites:* Enables create, query, update, and delete sites actions.
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 views for site tableau:content:read List all views on a site.

Troubleshoot scopes

401001 - signin error

If you encounter error 401001, the Sign In response body is appended with one of the following additional connected apps-specific error codes: 16, 10084, or 10085.

For example, in the following response body, "10084” is the connected apps error code you can use to help troubleshoot issues with signing in to Tableau Cloud using a JWT for REST API authorization.

<error code="401001">  
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

To help resolve the issue, refer to the description of the applicable error code and its potential causes.

  • 16: Could not find user—this error can occur because the incorrect "sub" (user name) was specified

  • 10084: Could not parse access token—this error can occur for the following reasons:

    • JWT is invalid or there was an unexpected problem
    • Incorrect "aud" (audience) was specified
    • For direct trust, there was a problem with signing the secret
  • 10085: Could not fetch secret to verify signature for client ID—this error can occur for the following reasons:

    • Incorrect client ID in "iss" specified
    • For direct trust, incorrect "kid" (secret ID) was specified
    • For OAuth 2.0 trust, unable to fetch keys from the JWKSource

401002 - unauthorized access error

If you encounter error 401002 and have confirmed that you have the appropriate permissions to make the request, ensure the scope included in the JWT is correct and matches the request you're trying to make. For a list of endpoints and supported scopes, see the REST API methods that support JWT authorization section above.

Thanks for your feedback!Your feedback has been successfully submitted. Thank you!