Permissions Methods
Using the permissions methods of the Tableau REST API you can:
- List, add, and delete granular default permissions that apply to new content created in a project
- List, add, and delete granular permissions for existing projects, workbooks, views, flows, metrics, Ask data lenses, and data sources
This functionality relates to the UI elements and concepts described at: Permissions Reference(Link opens in a new window).
Add Ask Data Lens Permissions - Retired in API 3.22
In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
Adds permissions to the specified ask data lens for a user or group. You can specify multiple sets of permissions using one request.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
URI
PUT /api/api-version/sites/site-luid/lenses/lens-luid/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the data source. |
lens-luid | The LUID of the data source to set permissions for. |
Request Body
<tsRequest>
<permissions>
<lens id="lens-luid" />
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
lens-luid | Required. The LUID of the ask data lens permissions are being configured for. |
user-luid | Optional (at least one user or group must be specified). The LUID of the user to add permissions for. |
group-luid | Optional. The LUID of the group to add permissions for. |
capability-name |
The capability to assign. For valid capabilities for a data source project are
ChangePermissions,
Delete,
Move,
Read,
Write.
For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users with server or site administrator permissions, and non-administrators that have ChangePermissions permission for the lens (either explicitly or implicitly), can add ask data lens permissions.
Response Code
200
Response Body
<tsResponse>
<permissions>
<lens id="lens-luid" name ="lens-name" />
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional grantee capability sets ... -->
</permissions>
</tsResponse>
Version
Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Delete, Move, Read, and Write. |
403 | 403004 | No permissions to set permissions. | A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source. |
404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
404 | 404006 | Lens not found | The specified lens doesn't correspond to an existing data source. |
404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Add Data Source Permissions
Adds permissions to the specified data source for a user or group. You can specify multiple sets of permissions using one call.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
If the request body includes a child workbook or <project> element, the request is invalid.
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to set permissions for. |
Request Body
<tsRequest>
<permissions>
<datasource id="datasource-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
datasource-id | The <datasource> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <datasource> element is included, the datasource-id value must match the data source ID in the URI. Any other attributes in the <datasource> element are ignored. |
user-id | The ID (not name) of the user to add permissions for. |
group-id | The ID (not name) of the group to add permissions for. |
capability-name |
The capability to assign. For valid capabilities for a data source project are
ChangePermissions,
Connect,
Delete,
ExportXml,
Read (view),
Write, and
SaveAs.
For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators or site administrators can add permissions only to a data source for which they have ChangePermissions permission (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:update
Response Code
200
Response Body
<tsResponse version-and-namespace-settings>
<permissions>
<datasource id="datasource-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write. |
403 | 403004 | No permissions to set permissions. | A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source. |
404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
404 | 404004 | Data source not found | The specified data source doesn't correspond to an existing data source. |
404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add Default Permissions
Adds default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also adds default permission rules for database or table resources in a project for a user or group. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project. For more information, see Permissions(Link opens in a new window).
Content owners can override default permissions for their content, but only if project permissions have not been locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the project. |
project-luid | The LUID of the project to set default permissions for. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
< !-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
< !-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
< !-- ... additional grantee capability sets ... -->
</permissions>
</tsRequest>
Attribute Values
user-luid | The LUID of the user to add default permissions for. |
group-luid | The LUID of the group to add permissions for. |
capability-name | The capability to assign. Valid capabilities for a workbook are
Valid capabilities for a data source are
Valid capabilities for a flow are
For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators can add permissions defaults for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:update
Response Code
200
Response Body
<tsResponse>
<permissions>
<database id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" name="oracle.test.example.com:1521"/>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
<capabilities>
<capability name="Read" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Version
Version 2.1 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability in the URI is invalid for a data source. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write. |
400 | 400042 | Malformed permissions qualifier | The request body includes a <workbook> or <datasource> element. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to add permissions on the project. |
404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user LUID in the request body as the grantee doesn't correspond to an existing user. |
404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project. |
404 | 404009 | Project ID mismatch | A project LUID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.) |
404 | 404012 | Group not found | A group LUID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add Project Permissions
Adds permissions to the specified project for a user or group. You can specify multiple sets of permissions using one call.
If the request body includes a child datasource or <project> element, the request is invalid.
URI
PUT /api/api-version/sites/site-id/projects/project-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the project. |
project-id | The ID of the project to set permissions for. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
user-id | The ID (not name) of the user to add permissions for. |
group-id | The ID (not name) of the group to add permissions for. |
capability-name |
The capability to assign permissions to. In Tableau Server 10.0, the valid
capabilities for a project are
ProjectLeader,
Read (view), and
Write.
For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators or site administrators can add permissions for a project only if they have ChangePermissions (version 2.0
) or
ProjectLeader (version 2.1
) permission for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:update
Response Code
200
Response Body
<tsResponse>
<permissions>
<project id="project-id" name="project-name" />
<owner id="project-owner-id" />
</project>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability specified in the request is not in the list of valid capability names for this method. The mode of the capability for ProjectLeader cannot be set to Deny. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to add permissions on the project. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user ID in the request body as the grantee doesn't correspond to an existing user. |
404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
404 | 404009 | Project ID mismatch | A project ID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.) |
404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add View Permissions
Adds permissions to the specified view (also known as a sheet) for a user or group. You can specify multiple sets of permissions using one call.
URI
PUT /api/api-version/sites/site-id/views/view-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the workbook view. |
view-id | The ID of the view to set permissions for. You can obtain this ID by calling Query Views for Site. |
Request Body
<tsRequest>
<permissions>
<view id="view-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
view-id | The view-id value must match the view ID in the URI. |
user-id | The ID (not name) of the user to add permissions for. |
group-id | The ID (not name) of the group to add permissions for. |
capability-name | The capability to assign. If any capability has already been
granted or denied for a specified user or group, that capability is ignored. For valid capabilities for a view are
AddComment, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.
For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
This method can only be called by server and site administrators, and user who have permission to set permissions on the workbook (either explicitly or implicitly). To use this method, the parent workbook that contains the specified view must have its showTabs attribute set to Hide. You can configure this setting by using the Update Workbook method.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:update
Response Code
200
Response Body
<tsResponse>
<permissions>
<view id="view-id" />
<owner id="owner-id"/>
</view>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<capability name="capability-name" mode="capability-mode" />
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<capability name="capability-name" mode="capability-mode" />
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.2 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability in the URI is invalid for a view. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the view. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404011 | View not found | The view ID in the URI doesn't correspond to an existing view. |
404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or an invalid capability value (other than Allow or Deny). |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/13020592-762f-4de4-a25e-f4beb005836e/views/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-view-permissions.xml
Example of add-view-permissions.xml:
<tsRequest>
<permissions>
<view id="34acb0d7-fa37-43d7-bdde-d6635eb724b5" />
<granteeCapabilities>
<user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" />
<capabilities>
<capability name="ExportImage" mode="Allow" />
<capability name="ChangePermissions" mode="Deny" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsRequest>
Example response:
<tsResponse>
<permissions>
<view id="34acb0d7-fa37-43d7-bdde-d6635eb724b5" name="What If Forecast">
<owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
</view>
<granteeCapabilities>
<group id="2aa47cfa-9f2b-11e8-a260-af4a26124661"/>
<capabilities>
<capability name="ShareView" mode="Allow"/>
<capability name="ViewComments" mode="Allow"/>
<capability name="Filter" mode="Allow"/>
<capability name="ExportData" mode="Allow"/>
<capability name="Read" mode="Allow"/>
<capability name="AddComment" mode="Allow"/>
<capability name="ViewUnderlyingData" mode="Allow"/>
<capability name="ExportImage" mode="Allow"/>
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
<capabilities>
<capability name="ExportImage" mode="Allow"/>
<capability name="ChangePermissions" mode="Deny"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Add Virtual Connection Permissions
Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the virtual connection. |
virtualconnection‑id | The ID of the virtual connection to set permissions for. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<!-- ...additional granteeCapability sets... -->
</permissions>
</tsRequest>
Attribute Values
user-id | The LUID of the user to add permissions for. A request does not need to include both a user and a group grantee. |
group-id | The LUID of the group to add permissions for. A request does not need to include both a user and a group grantee. |
capability-name | The capability to assign. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. |
Permissions
You must be an administrator or have the ChangePermissions permission for the virtual connection (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:update
Response Code
200
Response Body
<tsResponse>
<permissions>
<virtualConnection id="virtualconnection-luid"
name="virtual-connection-name">
<owner id="user-luid"/>
</virtualConnection>
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional granteeCapability sets ... -->
</permissions>
</tsResponse>
Version
Version 3.23 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. |
403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
404 | 404014 | Capability not found | A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | Request type was not PUT. |
400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, see Handling Errors.
Example
curl --location --request PUT 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest>
<permissions>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
<capabilities>
<capability name="read" mode="allow" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsRequest>'
Add Workbook Permissions
Adds permissions to the specified workbook for a user or group. You can specify multiple sets of permissions using one call.
URI
PUT /api/api-version/sites/site-id/workbooks/workbook-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the workbook. |
workbook-id | The ID of the workbook to set permissions for. |
Request Body
<tsRequest>
<permissions>
<workbook id="workbook-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
workbook-id | The <workbook> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <workbook> element is included, the workbook-id value must match the workbook ID in the URI. Any other attributes in the <workbook> element are ignored. |
user-id | The ID (not name) of the user to add permissions for. |
group-id | The ID (not name) of the group to add permissions for. |
capability-name | The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators or site administrators can call this method only if the have permission to set permissions on the workbook (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:update
Response Code
200
Response Body
<tsResponse>
<permissions>
<workbook id="workbook-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the workbook. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
404 | 404006 | Workbook not found | The workbook ID in the URI doesn't correspond to an existing workbook. |
404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add Workbook to Server Schedule
Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.
The task type must match the schedule type. For a list of schedule types, see Create a Schedule.
For Tableau Cloud, see Create Cloud Extract Refresh Task.
This method is not available for Tableau Cloud.
Starting in Tableau version 2022.1 (API v3.16), with the introduction of
View Acceleration(Link opens in a new window),
the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will
also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing
any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases
resulting in error codes being returned.
URI
PUT /api/api-version/sites/site-id/schedules/schedule-id/workbooks
Parameter Values
api-version | The version of the API to use, such as 3.24 .
For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the view. |
schedule-id | The ID of the schedule that you are associating with the workbook. |
Request Body
<tsRequest>
<task>
<extractRefresh>
<workbook id="workbook-id" />
</extractRefresh>
</task>
<task>
<dataAcceleration>
<workbook id="workbook-id" />
</dataAcceleration>
</task>
</tsRequest>
Attribute Values
workbook-id | The ID of the workbook to add to the schedule. |
Permissions
Only Tableau Server users who are server administrators or site administrators can add a workbook to a data acceleration schedule. Tableau Server users who are not server administrators or site administrators can only add a workbook to other types of schedules if they own the workbook, or are the project leader for the project that contains the workbook.
Response Code
200
Response Body
<tsResponse>
<task>
<extractRefresh id="extractRefresh-id" type="extractRefresh-type">
<schedule id="schedule-id" />
<workbook id="workbook-id" />
</extractRefresh>
</task>
</tsResponse>
Version
Starting in Tableau Server 10.5 (API 2.8) you can add a task to refresh a workbook extract. In Tableau Server 2020.2 (API 3.8)
through 2021.4 (API 3.15), you can add a task to add data acceleration to a workbook.
Starting in Tableau version 2022.1 (API v3.16), with the introduction of
View Acceleration(Link opens in a new window),
the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will
also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing
any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases
resulting in error codes being returned.
For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
401 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
403 | 403032 | Update Forbidden | A non-administrator user called this method, but the caller doesn't have sufficient permissions. |
404 | 404000 | Site not found | The site ID in the URI is unknown. |
404 | 404006 | Resource not found | The workbook ID in the request body is unknown. |
405 | 405000 | Invalid request method | Request type was not PUT. |
500 | 500000 | Internal Server Error | The schedule ID in the URI is unknown. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/
1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/workbooks" -X PUT
-H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"
Content of add-to-schedule.xml:
<tsRequest>
<task>
<extractRefresh>
<workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
</extractRefresh>
</task>
</tsRequest>
Example response:
<tsResponse>
<task>
<extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
<schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
<workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
</extractRefresh>
</task>
</tsResponse>
Delete Ask Data Lens Permission - Retired in API 3.22
In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau AI and Tableau Pulse are reimagining the data experience(Link opens in a new window).
Deletes the specified permissions to the specified ask data lens for a user or group.
URI
DELETE /api/api-version/sites/site-luid/lenses/lens-luid/permissions/groups/group-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/lenses/lens-luid/permissions/users/user-luid/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | Required. The LUID of the site that contains the view. |
lens-luid | Required. The LUID of the lens to delete permissions for. |
group-luid | Optional (one user or group must be specified). The LUID of the group to remove the permission for. |
user-luid | Optional. The LUID of the user to remove the permission for. |
capability-name | The capability to remove the permission for. The valid capabilities for a view are ChangePermissions, Delete, Move, Read, Write. For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. |
Request Body
None
Permissions
Users with server or site administrator permissions, and non-administrators that have Delete or ChangePermissions permission (either explicitly or implicitly) for the lens, can delete ask data lens permissions.
Response Code
204
Response Body
None
Version
Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid for an ask data lense. Valid capabilities for a lens are ChangePermissions, Delete, Move, Read, and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to delete permissions on the view. |
403 | 403039 | Project permissions locked | The parent project that contains the specified ask data lens has its permissions locked. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the URI doesn’t correspond to an existing user. |
404 | 404046 | Lens not found | The ask data lens LUID in the URI doesn't correspond to an existing view. |
404 | 404012 | Group not found | A group LUID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or an invalid capability value (other than Allow or Deny). |
404 | 404014 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete Data Source Permission
Removes the specified data source permission for the specified group or user.
URI
DELETE /api/api-version/sites/site-id/datasources/datasource-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/datasources/datasource-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to remove the permission for. |
group-id | The ID of the group to remove the permission for. |
user-id | The ID of the user to remove the permission for. |
capability-name | The capability to remove the permission for. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), Write, and SaveAs. For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can call this method only if they have permission to delete permissions from the data source (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:delete
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the data source. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404012 | Group not found | The group ID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete Default Permission
Removes default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also removes default permission rules for database or table resources in a project for a user or group. After removing default permission rules, new resources of the type you specify that are added to the project will no longer have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project.
URI
Workbooks:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks/groups/group-luid/capability-name/capability-mode
Data sources:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources/groups/group-luid/capability-name/capability-mode
Data roles:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles/groups/group-luid/capability-name/capability-mode
Lenses:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses/groups/group-luid/capability-name/capability-mode
Metrics:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics/groups/group-luid/capability-name/capability-mode
Flows:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows/groups/group-luid/capability-name/capability-mode
Virtual Connections:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections/groups/group-luid/capability-name/capability-mode
Databases:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases/groups/group-luid/capability-name/capability-mode
Tables:
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables/groups/group-luid/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The LUID of the site that contains the project. |
project-id | The LUID of the project to remove the default permission for. |
group-id | The LUID of the group to remove the default permission for. |
user-id | The LUID of the user to remove default permission for. |
capability-name | The capability to remove the permissions for. Valid capabilities for a workbook are
Valid capabilities for a data source are
Valid capabilities for a flow are
For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive. |
Request Body
None
Permissions
Users who are not server administrators can remove permissions for a project only if they have ProjectLeader permissions for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:delete
Response Code
204
Response Body
None
Version
Version 2.1 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permissions to remove permissions for the project. |
403 | 403095 | Delete permissions for flows forbidden | A non-administrator user called this method but doesn't have permissions to remove permissions for the project where the flow is located. |
404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user LUID in the URI doesn't correspond to an existing user. |
404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project. |
404 | 404012 | Group not found | A group LUID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI isn't assigned to the specified user or group. |
404 | 404013 | Capability not found | The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
404 | 404027 | Flow not found | The flow LUID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete Project Permission
Removes the specified project permission for the specified group or user.
URI
DELETE /api/api-version/sites/site-id/projects/project-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/projects/project-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the project. |
project-id | The ID of the project to remove the permission for. |
group-id | The ID of the group to remove the permission for. |
user-id | The ID of the user to remove project the permission for. |
capability-name |
The capability to remove the permission for. In Tableau Server 10.0, valid capabilities for a project are
ProjectLeader,
Read (view), and
Write.
For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can remove permissions for a project only if they have ChangePermissions (version 2.0
) or
ProjectLeader (version 2.1
) permissions for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:delete
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid for a project. For a list of valid capabilities, see the capability-name attribute earlier. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permissions to remove default permissions for the project. |
403 | 403004 | Delete forbidden | A non-administrative user tried to update the project, but does not have permissions to the project. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user ID in the URI doesn't correspond to an existing user. |
404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
404 | 404012 | Group not found | A group ID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI isn't assigned to the specified user or group. |
404 | 404013 | Capability not found | The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete View Permission
Deletes permission to the specified view (also known as a sheet) for a Tableau Server user or group.
URI
DELETE /api/api-version/sites/site-id/views/view-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/views/view-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the view. |
view-id | The ID of the view to delete permissions for. You can obtain this ID by calling Query Views for Site. |
group-id | The ID of the group to remove the permission for. |
user-id | The ID of the user to remove the permission for. |
capability-name | The capability to remove the permission for. The valid capabilities for a view are AddComment, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can delete permissions from a view only if they have ChangePermissions permissions on the view (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:delete
Response Code
204
Response Body
None
Version
Version 3.2 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid for a view. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to delete permissions on the view. |
403 | 403039 | Project permissions locked | The parent project that contains the specified view has its permissions locked. |
403 | 403096 | Parent workbook tabs enabled | The specified view currently has permissions inherited from its parent workbook. View permission can be deleted if the parent workbook has its tabs disabled. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the URI doesn’t correspond to an existing user. |
404 | 404011 | View not found | The view ID in the URI doesn't correspond to an existing view. |
404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or an invalid capability value (other than Allow or Deny). |
404 | 404014 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/fbfa6f03-982c-4930-8ec1-d5949a19125d/views/0524c7ce-250b-45b1-adf2-d08f1648643c/permissions/users/ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1/AddComment/Allow" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Delete Virtual Connection Permission
Removes the specified virtual connection permission for the specified group or user.
URI
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the virtual connection. |
virtualconnection‑id | The ID of the virtual connection to remove the permission for. |
group-id | The LUID of the group to remove the permission for. A request does not need to include both a user and a group grantee. |
user-id | The LUID of the user to remove the permission for. A request does not need to include both a user and a group grantee. |
capability-name | The capability to remove the permission for. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. |
Request Body
None
Permissions
You must be an administrator or have the Delete permission for the virtual connection (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:delete
Response Code
204
Response Body
None
Version
Version 3.23 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. |
403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
404 | 404012 | Group not found | The group ID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
404 | 404014 | Capability not found | A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, see Handling Errors.
Example
curl --location --request DELETE 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/read/allow' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Delete Workbook Permission
Deletes the specified permission from the specified workbook for a group or user.
URI
DELETE /api/api-version/sites/site-id/workbooks/workbook-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/workbooks/workbook-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the workbook. |
workbook-id | The ID of the workbook to remove the permission for. |
group-id | The ID of the group to remove the permission for. |
user-id | The ID of the user to remove the permission for. |
capability-name | The capability to remove the permission for. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, Write, RunExplainData, and CreateRefreshMetrics. For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can delete permissions from a workbook only if they have ChangePermissions permission for workbook (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:delete
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read, Share_view, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to delete permissions from the workbook. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
404 | 404006 | Workbook not found | The workbook ID in the URI doesn't correspond to an existing workbook. |
404 | 404012 | Group not found | The group ID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny at the end of the URI. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
List Ask Data Lens Permissions
List all permissions configured for the specified ask data lens that the user has read capability for.
URI
GET /api/api-version/sites/site-luid/lens/lens-Luid/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the metrics. |
lens-luid | The LUID of the ask data lens whose permissions are being listed. |
Request Body
None
Permissions
Users with server or site administrator permissions, and non-administrators that have Read permission (either explicitly or implicitly), can list permissions for an ask data lens.
luResponse Code
200
Response Body
<tsResponse>
<permissions>
<parent type="Project" id="project-luid" />
<lens id="lens-luid" name ="lens-name/>
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability" mtode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
<-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
<-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<-- ... additional grantee capability sets ... -->
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the lens' permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project.
Version
Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
403 | 403018 | Read forbidden | A non-administrator user attempted to query metrics for the site, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404046 | Lens not found | A lens with the requested LUID could be found. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
List Data Source Permissions
Returns a list of permissions for a specific data source.
URI
GET /api/api-version/sites/site-id/datasources/datasource-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to get permissions for. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can view a data source only if they have Read (view) permission for the data source (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:read
Response Code
200
Response Body
<tsResponse>
<permissions>
<parent type="Project" id="project-id"
<datasource id="datasource-id"
owner="owner-user-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<parent type="Project" id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
<permissions>
<datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="USPS-rates">
<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
</datasource>
<granteeCapabilities>
<group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" />
<capabilities>
<capability name="Connect" mode="Allow"/>
<capability name="Read" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
List Default Permissions
Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, this method can also return details of default permission rules granted to users and groups for database or table resources in a project.
URI
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the project. |
project-luid | The LUID of the project to get default permissions for. |
Request Body
None
Permissions
Users who are not server administrators can query default permissions for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
Note: The following scope applies to data sources, workbooks, and metrics only.
tableau:permissions:read
Response Code
200
Response Body
<tsResponse>
<permissions>
<project id="project-luid" name="project-name" />
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability" mode="capability-mode" />
<capability name="capability" mode="capability-mode" />
<... additional capabilities ...>
</capabilities>
</granteeCapabilities>
<... additional grantee capabilities ...>
</permissions>
</tsResponse>
Version
Version 2.1 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
403 | 403035 | Querying data source permissions forbidden | The caller doesn't have permissions to query the project's default permissions for data sources. |
403 | 403036 | Querying workbook permissions forbidden | The caller doesn't have permissions to query the project's default permissions for workbooks. |
403 | 403035 | Querying flow permissions forbidden | The caller doesn't have permissions to query the project's default permissions for flows. |
404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project. |
For more information, see Handling Errors.
List Project Permissions
Returns information about the set of permissions allowed or denied for groups and users in a project.
URI
GET /api/api-version/sites/site-id/projects/project-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the project. |
project-id | The project to get permissions for. |
Request Body
None
Permissions
This method can only be called by server administrators and site administrators.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:read
Response Code
200
Response Body
<tsResponse>
<permissions>
<project id="project-id" name="project-name" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="capability-mode" />
<capability name="capability" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capabilities ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<permissions>
<project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="default">
<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
</project>
<granteeCapabilities>
<group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
<capabilities>
<capability name="Read" mode="Allow"/>
<capability name="Write" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
List View Permissions
Returns a list of permissions for the specific view.
URI
GET /api/api-version/sites/site-id/views/view-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the view. |
view-id | The ID of the view to get permissions for. |
Request Body
None
Permissions
This method can only be called by server and site administrators, and users who have Read (view) permission for the specific view.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:read
Response Code
200
Response Body
<tsResponse>
<parent type="Project" id="project-id" />
<permissions>
<view id="view-id"/>
<owner id="owner-id"/>
</view>
<granteeCapabilities>
<user id="user-id"/>
<capabilities>
<capability name="capability-name" mode="capability-mode"/>
<capability name="capability-name" mode="capability-mode"/>
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="user-id"/>
<capabilities>
<capability name="capability-name" mode="capability-mode"/>
<capability name="capability-name" mode="capability-mode"/>
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id"/>
<capabilities>
<capability name="capability-name" mode="capability-mode"/>
... additional capabilities ...
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the view's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.2 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the view. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404011 | View not found | The view ID in the URI doesn't correspond to an existing view. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/0524c7ce-250b-45b1-adf2-d08f1648643c/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse>
<permissions>
<view id="0524c7ce-250b-45b1-adf2-d08f1648643c"/>
<owner id="1a5dffe8-2439-4862-9eb0-46d055ef7379"/>
</view>
<granteeCapabilities>
<group id="9e617a5c-a733-11e8-8ec3-b748ab3bf3d6"/>
<capabilities>
<capability name="ViewComments" mode=mode="Allow"/>
<capability name="ExportData" mode=mode="Allow"/>
<capability name="AddComment" mode=mode="Allow"/>
<capability name="Filter" mode=mode="Allow"/>
<capability name="ViewUnderlyingData" mode=mode="Allow"/>
<capability name="Read" mode=mode="Allow"/>
<capability name="ShareView" mode=mode="Allow"/>
<capability name="ExportImage" mode=mode="Allow"/>
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="1a5dffe8-2439-4862-9eb0-46d055ef7379"/>
<capabilities>
<capability name="ExportImage" mode=mode="Allow"/>
<capability name="AddComment" mode=mode="Allow"/>
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1"/>
<capabilities>
<capability name="AddComment" mode=mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
List Virtual Connection Permissions
Returns a list of permissions for a specific virtual connection.
URI
GET /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the virtual connection. |
virtualconnection‑id | The ID of the virtual connection to get permissions for. |
Request Body
None
Permissions
You must be an administrator or have the Read (View) permission for the virtual connection (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:read
Response Code
200
Response Body
<tsResponse>
<permissions>
<parent id="project-luid"
type="Project"/>
<virtualConnection id="virtualconnection-luid"
name="virtualconnection-name">
<owner id="owner-luid"/>
</virtualConnection>
<granteeCapabilities>
<group id="group-luid"/>
<capabilities>
<capability name="capability-name"
mode="capability-mode"/>
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="user-luid"/>
<capabilities>
<capability name="capability-name"
mode="capability-mode"/>
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<!-- ...additional granteeCapability sets... -->
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.23 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Virtual Connection not found | The virtual connection ID in the URI doesn't correspond to an existing virtual connection. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl --location 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
List Workbook Permissions
Returns a list of permissions for the specific workbook.
URI
GET /api/api-version/sites/site-id/workbooks/workbook-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the workbook. |
workbook-id | The ID of the workbook to get permissions for. |
Request Body
None
Permissions
This method can only be called by server administrators and site administrators.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:read
Response Code
200
Response Body
<tsResponse>
<parent type="Project" id="project-id" />
<permissions>
<workbook id="workbook-id" name="workbook-name >
<owner="owner-user-id" />
</workbook>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="capability-mode" />
... additional capabilities for users ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="capability-mode" />
... additional capabilities for groups ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404006 | Workbook not found | The workbook ID in the URI doesn't correspond to an existing workbook. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<parent type="Project" id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
<permissions>
<workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance">
<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
</workbook>
<granteeCapabilities>
<group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
<capabilities>
<capability name="Read" mode="Allow"/>
<capability name="Filter" mode="Allow"/>
<capability name="ViewUnderlyingData" mode="Allow"/>
<capability name="ExportImage" mode="Allow"/>
<capability name="ExportData" mode="Allow"/>
<capability name="AddComment" mode="Allow"/>
<capability name="ViewComments" mode="Allow"/>
<capability name="ShareView" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Replace Project's Default Permissions
Replaces default permissions in the specified content. If Tableau Catalog is enabled, it also adds default permission rules for database or table resources in a project. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project. For more information, see Permissions(Link opens in a new window).
Version: Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: Users who are not server administrators, project owners, or project leaders can replace permissions defaults for a project only if they have effective ChangePermissions permission. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:permissions:update Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | The LUID for the site. |
project-luid | The LUID for the project. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
<capabilities>
<capability name="AddComment" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="2aa47cfa-9f2b-11e8-a260-af4a26124661" />
<capabilities>
<capability name="ViewComments" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional grantee capability sets ... -->
</permissions>
</tsRequest>
Request Attributes
user-luid | The LUID of the user to add default permissions for. |
group-luid | The LUID of the group to add permissions for. |
capability-name | The capability to assign. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, SaveAs, Read (view), and Write. For more information, see Permissions. |
cURL Request Example
curl --location "http://MY-SERVER/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/default-permissions/dataroles" --header "Content-Type: application/xml" --data @replace-default-permissions-workbook.xml
Response Code
200
Response Body
None
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability in the URI is invalid for a data source. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write. For detailed information about capabilities for each content type, see Capabilities. |
400 | 400042 | Malformed permissions qualifier | The request body includes a <workbook> or <datasource> element. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to add permissions on the project. |
404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user LUID in the request body as the grantee doesn't correspond to an existing user. |
404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project. |
404 | 404009 | Project ID mismatch | A project LUID specified in the URI doesn’t match the project ID specified in the request body. (You don’t have to specify a project ID in the request body.) |
404 | 404012 | Group not found | A group LUID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | The request type wasn’t POST. |
For more information, see Handling Errors.
Replace Content Permissions
Replaces existing permissions in the specified content. You can specify multiple sets of permissions using one call.
Version: Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)
License: No additional license required
Permissions: Users who are not server administrators or site administrators can add permissions only to content for which they have ChangePermissions permission. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:permissions:update Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/datasources/datasource-luid/permissions
POST /api/api-version/sites/site-luid/flows/flow-luid/permissions
POST /api/api-version/sites/site-luid/projects/project-luid/permissions
POST /api/api-version/sites/site-luid/views/view-luid/permissions
POST /api/api-version/sites/site-luid/workbooks/workbook-luid/permissions
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | The LUID for the site. |
datasourc-luid | The LUID for the data source. |
flow-luid | The LUID for the flow. |
project-luid | The LUID for the project. |
view-luid | The LUID for the view. |
workbook-luid | The LUID for the workbook. (Optional, but can be included for compatibility with older versions.) |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
<capabilities>
<capability name="AddComment" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="2aa47cfa-9f2b-11e8-a260-af4a26124661" />
<capabilities>
<capability name="ViewComments" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional grantee capability sets ... -->
</permissions>
</tsRequest>
Request Attributes
workbook-id | The <workbook> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <workbook> element is included, the workbook-id value must match the workbook ID in the URI. Any other attributes in the <workbook> element are ignored. |
user-id | The ID (not name) of the user to add permissions for. |
group-id | The ID (not name) of the group to add permissions for. |
cURL Request Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @replace-view-permissions.xml
Response Code
200
Response Body
None
Errors
HTTP status | error Code | Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the workbook. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
404 | 404006 | Workbook not found | The workbook ID in the URI doesn't correspond to an existing workbook. |
404 | 404011 | View not found | The view ID in the ID doesn't correspond to an existing view. |
404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | The request type was not POST. |
For more information, see Handling Errors.