--- schema_version: "1" id: cc988dac1529749a57a37befc5038ea4ea9b13dec6d910caecbbae7ba03d175b title: Access Scopes for Connected Apps collection: tableau version: current locale: en-us portal_url: https://docs.salesforce.com/tableau/current/en-us/online/connected_apps_scopes.md canonical_url: https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm source_site: help.tableau.com content_type: documentation content_hash: de53b956b4c045ac4c8f983d29bbad0ea82c16c923520691b5e5fbd710c46394 description: Reference of access scopes that authorize REST API methods for connected apps via JWT. --- [Skip to main content](#main-content) # 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](#scopes) (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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#update_data_source) 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](https://help.tableau.com/current/api/metadata_api/en-us/docs/meta_api_auth.html). Starting in Tableau Cloud February 2025, you also specify this scope in a JWT that will be used to create a credentials token for use with the [VizQL Data Service](https://help.tableau.com/current/api/vizql-data-service/en-us/index.html). **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:](#wildcard)** 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:](#cross)** 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: - [Configure Connected Apps with Direct Trust](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm) - [Configure Connected Apps with OAuth 2.0 Trust](https://help.tableau.com/current/online/en-us/connected_apps_eas.htm) 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_authentication.htm#sign_in) 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`](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_auth.htm#using_auth_token) 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. ``` ``` **Response body** The Sign In request produces the following response body, which includes the Tableau credentials token. ``` ``` After the Tableau credentials token is generated, add it 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 Scopes for connected apps grants your custom application access to Tableau REST API capabilities on users' behalf ### How to find scopes You can find the required scope for a JWT-supported method in its properties block in the [Tableau REST API](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm) Help. If a scope is not listed in the method’s properties block, access to that method can’t be controlled by a JWT. For example, a scope that allows you to call the [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#query_site) method in the Tableau REST API is `tableau:sites:read`. **Notes:** - Both the [Sign In](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_authentication.htm#sign_in) and [Sign Out](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_authentication.htm#sign_out) methods are supported by JWT authorization but do not require scopes to use beginning in June 2023 (Tableau 2023.2). - For scopes supported by the Embedding API v3, see one of the following: - [Configure Connected Apps with Direct Trust](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm) - [Configure Connected Apps with OAuth 2.0 Trust](https://help.tableau.com/current/online/en-us/connected_apps_eas.htm) - Starting in December 2025, listed scopes also support REST API authorization through unified access tokens (UATs). This means connected apps and UAT scopes are the same. ### Type of scopes #### About wildcard (\*) scopes Wildcard scopes use the wildcard character (\*) instead of a specific action, to enable multiple supported actions within a specific Tableau REST API category. #### Examples
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.
#### About cross-category scopes Cross-category scopes enable multiple supported actions across multiple Tableau REST API categories. #### Examples
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.
## 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. "summary": "Signin Error", "detail": "Error signing in to Tableau Cloud (10084)" 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](#scopes) section above.