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

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

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

  • AddComment
  • ChangeHierarchy
  • ChangePermissions
  • Delete
  • ExportData
  • ExportImage
  • ExportXml
  • Filter
  • Read (view)
  • ShareView
  • ViewComments
  • ViewUnderlyingData
  • WebAuthoring
  • Write
  • RunExplainData
  • CreateRefreshMetrics

Valid capabilities for a data source are

  • ChangePermissions
  • Connect
  • Delete
  • ExportXml
  • SaveAs
  • Read (view)
  • Write

Valid capabilities for a flow are

  • ChangeHierarchy
  • ChangePermissions
  • Delete
  • ExportXml (download)
  • Execute
  • Read (view)
  • WebAuthoringForFlows
  • 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 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

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

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

  • AddComment
  • ChangeHierarchy
  • ChangePermissions
  • Delete
  • ExportData
  • ExportImage
  • ExportXml
  • Filter
  • Read (view)
  • ShareView
  • ViewComments
  • ViewUnderlyingData
  • WebAuthoring
  • Write
  • RunExplainData
  • CreateRefreshMetrics

Valid capabilities for a data source are

  • ChangePermissions
  • Connect
  • Delete
  • ExportXml
  • SaveAs
  • Read (view)
  • Write

Valid capabilities for a flow are

  • ChangeHierarchy
  • ChangePermissions
  • Delete
  • ExportXml (download)
  • Execute
  • Read (view)
  • WebAuthoringForFlows
  • 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

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.

lu

Response 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 statuserror CodeConditionDetails
403403018Read forbiddenA non-administrator user attempted to query metrics for the site, but the caller doesn't have Read permission.
404404000Site not foundThe site ID in the URI doesn't correspond to an existing site.
404404046Lens not foundA lens with the requested LUID could be found.
405405000Invalid request methodRequest 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

Copy 
<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>

Copy 
{
  "permissions": [
    {
      "user": {
        "id": "user-luid"
      },
      "capabilities": [
        {
          "name": "capability-name",
          "mode": "capability-mode"
        }
      ]
    },
    {
      "group": {
        "id": "group-luid"
      },
      "capabilities": [
        {
          "name": "capability-name",
          "mode": "capability-mode"
        }
      ]
    }
  ]
}

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

Copy 
<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>

Copy 
{
  "permissions": {
    "granteeCapabilities": [
      {
        "user": {
          "@id": "user-luid"
        },
        "capabilities": {
          "capability": {
            "@name": "capability-name",
            "@mode": "capability-mode"
          },
          "#text": "... additional capabilities ..."
        }
      },
      {
        "group": {
          "@id": "group-luid"
        },
        "capabilities": {
          "capability": {
            "@name": "capability-name",
            "@mode": "capability-mode"
          },
          "#text": "... additional capabilities ..."
        }
      }
    ],
    "#text": "... additional grantee capability sets ..."
  }
}

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.


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