Permissions


Users who call REST API methods must have permission to perform the task represented by each method that they call. A user's set of permissions is determined by the user's identity—that is, by the credentials that the user passes when calling Sign In. Many methods, such as adding or removing users from the server, require the user to be a server administrator. Other methods can be called by any user who has been granted appropriate permissions to perform the task that is represented by the method. The documentation for individual methods indicates the permissions that are required in order to call that method.

Note: The documentation occasionally refers to explicit and implicit permissions. For example, the Permissions section for the Download Datasource method indicates that the users can call the method "only if they have ExportXml permission for the data source (either explicitly or implicitly)." Explicit permissions are those that have been assigned to the user. If you query a user's permissions, explicit permissions are listed in the display. In contrast, implicit permissions are those that the user has because the user is a server administrator, or the owner of an entity. Administrators do not have to be explicitly granted any permissions, and owners do not have to be granted permissions for content that they own (including projects under parent projects that they own). The term implicit is used because if you query the user's permissions, the user's implicit permissions are not listed.

Using the REST API to assign permissions

You can use methods in the REST API to assign or edit permissions for projects, workbooks, and data sources. For example, you might call Create Project to create a new project and then call Add Project Permissions to assign appropriate permissions to the new project. When you add permissions to an entity like a project, you specify the following information:

  • The grantee, that is, the user, group, or group set that you are assigning the permission to. (A grantee is sometimes referred to as a principal.) Grantees are identified by ID (LUID), not name.

  • The capability that you're assigning permissions to. You specify the capability using a reserved name that's defined in the REST API XML schema, such as Read, Write, ExportData, or WebAuthoring. (These reserved names correspond to names that are used in the server environment, as listed later in this topic.)

  • The mode for the permission, which is either Allow or Deny.

Individual entities (project, workbook, and data source) support different capabilities. For example, for a data source, you can assign permissions only for the ChangePermissions, Connect, Delete, ExportXml, Read, and Write capabilities. In contrast, for a workbook, you can assign permissions for the AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write capabilities. The documentation for an individual API (such as Add Workbook Permissions or Add Project Permissions) specifies the capabilities that you can pass for that API.

The following example shows what the body of an Add Project Permissions request might look like. This example assigns the Allow permission to the Read and Write capabilities of the project for the user whose ID is 9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d.

<tsRequest>
  <permissions>
    <granteeCapabilities>
      <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
      <capabilities>
        <capability name="Read" mode="Allow" />
        <capability name="Write" mode="Allow" />
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsRequest>

Project default permissions and permissions locking

Starting in Tableau Server 9.2 (REST API version 2.1), server administrators, site administrators, and project leaders can define default permissions for a project. These permissions are then assigned by default to content that's published to the server. You can use the following REST API methods to work with project default permissions:

Administrators and project leaders can also "lock" these default permissions. In that case, the project default permissions are assigned to content when it's published, and the permissions for that content cannot be changed, even by the content owner. To lock permissions to the project, you include the contentPermissions attribute in the Create Project(Link opens in a new window) or Update Project(Link opens in a new window) method and set the attribute's value to LockedToProject. (The default value for this attribute is ManagedByOwner.)

Note: Starting in Tableau Server 9.2, you can set permissions for only these capabilities in a project: Read (view), Write (save), and ProjectLeader. (In Tableau Server 9.1 and earlier, you could set capabilities that could apply to all content in the project.) This is a change in the permissions model for Tableau Server itself, not just in the API. In Tableau Server 9.2, you cannot set permissions for any project capability except the ones listed here, even if you specify a previous version of the REST API in the URI.

For more information, see these topics in the Tableau Server documentation:

Inherited permissions for nested projects

When a user has Project Leader permissions for a project in a hierarchy, they will have the InheritedProjectLeader permission for any child projects under that project in the hierarchy, even if Project Leader permissions are explicitly denied for that user in a child project. To learn more, see Manage Permissions with Projects.

Mapping capability names in the REST API to names in the server environment

When you call a method that lets you assign permissions to an entity, such as Add Datasource Permissions, you refer to the permissions using a set of capabilities whose names are defined in the REST API XML Schema. The names of the capabilities defined in the schema don't always correspond exactly to how the capabilities are presented in the Tableau Server environment. The following table shows permission names as they are used in the REST API and as they appear in the server environment.

REST API permission name Server environment permission name
AddComment Add Comment
ChangeHierarchy Move
ChangePermissions Set Permissions
Connect Connect
Delete Delete
Execute Run Flow
ExportData View Summary Data
ExportImage Export Image
ExportXml Download
Filter Filter
InheritedProjectLeader Project Leader
ProjectLeader Project Leader
Read View
ShareView Share Customized
ViewComments View Comments
ViewUnderlyingData View Underlying Data
WebAuthoring Web Edit
Write Save

More Information

For more information about permissions and capabilities, see Permissions(Link opens in a new window) topic in the Tableau Server Help.


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