Users and Groups Methods

Using the groups and users methods of the Tableau Server REST API you can do the operations listed in the following categories:

Groups (groups of Tableau Server users)

  • Create a local group of users for a site or import users to a new local group from Active Directory
  • Delete a group from a site
  • Get a filtered, sorted list of groups of a site
  • Update a local group name or refresh the users from Active Directory
  • List, add, or delete users of a group

Site Users (users of a site)

  • Get a filtered, sorted list of users of a site
  • Add or delete users of a site
  • Get or update the details of a user of a site

This functionality relates to the UI elements and concepts described at: Manage Users and Groups(Link opens in a new window).

Create Group

Creates a group in Tableau Server. If the server is configured to use Active Directory for authentication, this method can create a group in Tableau Server and then import users from an Active Directory group.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

To add users to a group, call Add User To Group. To make changes to an existing group, call Update Group.

If you use the method to import users from an Active Directory, the import process can be performed immediately (synchronously) or as a background job (asynchronously).

Note: If Active Directory contains a large number of users, you should import them asynchronously; otherwise, the process can time out.

The Create Group response returns information in two ways: in the response header and in the response body. The ID of the new group is always returned as the value of the Location header. If you create a local group or import an Active Directory group immediately, the response body contains the name and ID of the new group. If you import an Active Directory group using a background process, the response body contains a <job> element that includes a job ID. You can use the job ID to check the status of the operation by calling Query Job.

URI

POST /api/api-version/sites/site-id/groups

POST /api/api-version/sites/site-id/groups?asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site to create the group in.
asJob-value A Boolean value that is used if you are importing from Active Directory. If you set this to false (the default), the import process runs as a synchronous process. If the Active Directory group contains many users, the process might time out before it finishes.

If you set this to true, the process runs asynchronously. In that case, Tableau Server starts a job to perform the import and returns the job ID in the Location header. You can check the status of the import job by calling Query Job.

Note: This parameter has no effect if the server is configured to use local authentication.

Request Body

Creating a local group:

<tsRequest>
  <group name="new-tableau-server-group-name"
    grantLicenseMode="license-mode"
    siteRole="minimum-site-role"/>
</tsRequest>

Importing a group from Active Directory:

<tsRequest>
  <group name="active-directory-group-name" >
    <import source="ActiveDirectory"
      domainName="active-directory-domain-name"
      siteRole="minimum-site-role"
      grantLicenseMode="license-mode" />
  </group>
</tsRequest>

When the request is to create a group with grantLicenseMode, a siteRole value should also be supplied.

When the request body contains an <import> element, a Tableau Server configured to authenticate via Active Directory will create the group in Tableau Server and modify the set of users in the group to be the same as those in Active Directory. The source attribute of the <import> element must be set to ActiveDirectory.

Note: When a group is created by importing from Active Directory, Tableau Server uses the value of the Active Directory sAMAccountName attribute as the user name.

Attribute Values

new-tableau-server-group-name The name for the new group.
active-directory-group-name

The name of the Active Directory group to import.

active-directory-domain-name

The domain of the Active Directory group to import.

minimum-site-role

Required if an import element or grantLicenseMode attribute are present in the request. The site role assigned to users who are imported from Active Directory or granted a license automatically using the grant license on-sync or on-login mode.

If the requested user name matches an existing user in the group, the user either retains their existing role or are granted the one specified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to is imported from Active Directory or local.

Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows.

  1. Unlicensed
  2. Viewer
  3. Explorer
  4. ExplorerCanPublish
  5. Creator
  6. SiteAdministratorExplorer

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

license-mode

Optional. The mode for automatically applying licenses for group members. When the mode is onLogin, a license is granted for each group member when they login to a site.

For local groups, the mode can be either onLogin or unset. If the attribute is omitted, the default mode is unset, which results in no licenses being granted automatically to group members.

For groups that import an Active Directory domain, the mode can be either onSync or onLogin. If the attribute is omitted, the default mode is onSync where licenses are granted for group members each time the domain is synced.

The minimum role granted to users through grantLicenseMode is specified in the siteRole attribute. If that role has less permissions than an existing role assigned to the user, then the user's permissions remain unchanged.

Permissions

This method can only be called by server administrators and site administrators.

Response Code

201, for creating a local group and for importing immediately.

202, for importing using a background process.

Response Headers

Location: /api/3.9/sites/site-id/groups/new-group-id

Response Body

Creating a local group:

<tsResponse>
  <group id="new-group-id"
	name="group-name"
	grantLicenseMode="license-mode"
	siteRole="minimum-site-role"/>
</tsResponse>

Creating a group and importing from Active Directory immediately:

<tsResponse>
  <group id="new-group-id"
    name="group-name" />
	  <import domainName="active-directory-domain-name”
        siteRole="default-site-role"
		grantLicenseMode="onLogin" />
	 </group>
</tsResponse>

Importing as a background process:

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="GroupImport"
    progress="0" createdAt="time-job-created" />
</tsResponse>

Version

Version 3.9 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 400013 Invalid site role

The value of the siteRole attribute must be Creator, Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

400 400019 Malformed import element When the <import> element is present in the request body, the following attributes must be specified: source with the value ActiveDirectory; domainName; and siteRole If any of these is missing, the element is malformed.
403 403011 ActiveDirectory is not configured The <import> element is present, but Tableau Server is configured for local authentication.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404016 Domain not found The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory.
404 404017 Active Directory group not found The request body includes an <import> element, but no group exists in Active Directory that matches the specified group name.
405 405000 Invalid request method Request type was not POST.
409 409009 Group name conflict The group name in the request already belongs to the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

For more information, see Handling Errors.

Example: Local Group

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-local-group.xml

Content of create-local-group.xml:

<tsRequest>
  <group name="marketing-group" />
</tsRequest>

Response header:

Location: /api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d

Response body:

<tsResponse version-and-namespace-settings>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group" />
</tsResponse>

Example: Active Directory Group

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-ad-group.xml

Content of create-ad-group.xml:

<tsRequest>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group" />
    <import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" />
  </group>
</tsRequest>

Response header:

Location: /api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d

Response body:

<tsResponse version-and-namespace-settings>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group" >
	  <import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" />
  </group>
</tsResponse>

Add User to Group

Adds a user to the specified group.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

POST /api/api-version/sites/site-id/groups/group-id/users

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to add the user to.

Request Body

<tsRequest>
  <user id="user-id" />
</tsRequest>

Attribute Values

user-id The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site .

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
    name="user-name"
    siteRole="site-role" />
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

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.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 Group not found The group name in the request body doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not POST.
409 409011 User conflict The specified user is already a member of the group.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-group.xml

Content of add-user-to-group.xml:

<tsRequest>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</tsRequest>

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
  <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Adam"
        siteRole="Explorer" />
</tsResponse>

Add User to Site

Adds a user to Tableau Server and assigns the user to the specified site.

If Tableau Server is configured to use local authentication, the information you specify is used to create a new user in Tableau Server.

Note: After creating the user, you must set a full name, password, and email address for the user with the call to Update User. If you are using SAML with local authentication, the user information that you add is not synchronized with the SAML IdP, as it would be if you were using Active Directory. Even if it is not used by SAML, the user information must be present.

If Tableau Server is configured to use Active Directory for authentication, the user you specify is imported from Active Directory into Tableau Server.

When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

If you try to add a user using a specific site role but you have already reached the limit on the number of licenses for your users, the user is added as an unlicensed user. In that case, the response code is 201 (which indicates success), but the siteRole value in the response body is set to Unlicensed.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

POST /api/api-version/sites/site-id/users

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site to add users to.

Request Body

<tsRequest>
  <user name="user-name"
        siteRole="site-role"
        authSetting="auth-setting" />
</tsRequest>

Attribute Values

user-name

The name of the user. If the server uses local authentication, this can be any name. If you are using Active Directory authentication, or if you are using Tableau Online, there are specific requirements for the name.

For Tableau Server:
If Tableau Server uses Active Directory authentication, this must be the name of an existing user in Active Directory. If the user name is not unique across domains, you must include the domain as part of the user name (for example, example\Adam or adam@example.com).

Note: Active Directory specifies a user name using two attributes: sAMAccountName and userPrincipalName (UPN) prefix. For most Active Directory users, these attributes are the same. By default, if you are adding a user from Active Directory, the name that you provide in the user-name is matched against the Active Directory sAMAccountName attribute, which becomes the name that the user signs in to Tableau Server with.

Two exceptions are when the name that you provide: is longer than 20 characters; and includes an @ character. In these cases, Tableau imports the user using the Active Directory UPN. For more information, see User Naming Attributes(Link opens in a new window) on the MSDN site.

For Tableau Online:
The user-name is the email address that the user will use to sign in to Tableau Online. When you add a user to the site, Tableau Online sends an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

site-role

The site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

new-auth-setting

(Optional) The authentication type for the user.

(For Tableau Server: This attribute only applies when adding users to sites with site-specific SAML enabled in settings.)

You can assign the following values for this attribute:

Permissions

This method can only be called by server administrators and site administrators.

Response Code

201

Response Body

<tsResponse>
  <user id="user-id"
   name="user-name"
   siteRole="site-role"
   authSetting="auth-setting" />
</tsResponse>

Response Headers

Location: /api/3.9/sites/site-id/users/new-user-id

Version

Version 1.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 400013 Invalid site role

The value of the siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The server is configured to use Active Directory for authentication, and the username specified in the request body doesn't match an existing user in Active Directory.
405 405000 Invalid request method Request type was not POST.
409 409000 User conflict The specified user already exists on the site.
409 409005 Guest user conflict The Tableau Server API doesn't allow adding a user with the guest role to a site.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-site.xml

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site to add the user to, as returned by a previous call to Sign In.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the authentication returned by a previous call to Sign In.

Content of add-user-to-site.xml:

<tsRequest>
  <user name="Adam"
    siteRole="Explorer" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
    name="Adam"
    siteRole="Explorer"
    authSetting="ServerDefault"  />
</tsResponse>

Get Users in Group

Gets a list of users in the specified group.

URI

GET /api/api-version/sites/site-id/groups/group-id/users

GET /api/api-version/sites/site-id/groups/group-id/users?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to get the users for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
      totalAvailable="total-available" />
	    <users>
	      <user id="user-id"
	    name="user-name"
	    siteRole="site-role"
	    lastLogin="last-login-date-time"
	    externalAuthUserId="authentication-id-from-external-provider"
		language="language-code"
		locale="locale-code" />
	    ... additional user information ...
   </users>
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value is returned for Tableau Online; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value of lastLogin is an empty string.

Version

Version 2.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <users>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Adam" siteRole="Explorer" />
    <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Bob" siteRole="ExplorerCanPublish"
	language="en-GB" locale="GB" />
  </users>
</tsResponse>

Get Users on Site

Returns the users associated with the specified site.

URI

GET /api/api-version/sites/site-id/users

GET /api/api-version/sites/site-id/users?filter=filter-expression

GET /api/api-version/sites/site-id/users?sort=sort-expression

GET /api/api-version/sites/site-id/users?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/users?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the users.
filter-expression (Optional) An expression that lets you specify a subset of users to return. You can filter on predefined fields such as name and lastLogin. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the views or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand &.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
   <users>
    <user id="user-id"
      name="user-name"
      siteRole="site-role"
      lastLogin="date-time"
      externalAuthUserId="authentication-id-from-external-provider"
      authSetting="auth-setting"
	  language="language-code"
 	  locale="locale-code" />
    <user id="user-id"
      name="user-name"
      siteRole="site-role"
      lastLogin="date-time"
      externalAuthUserId="authentication-id-from-external-provider"
	  authSetting="auth-setting"
	  language="language-code"
	  locale="locale-code" />

  </users>
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value is returned for Tableau Online; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value of lastLogin is an empty string.

Note: The authSetting attribute is only returned if you are using Tableau Server with site-specific SAML enabled, or Tableau Online with either SAML or OpenID enabled.

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="161"/>
  <users>
    <user id="9f9e9d9c8-b8a8-f8e7-d7c7-b7a6f6d6e6d" name="Ashley"
      siteRole="Viewer" language="en-GB" locale="GB" />
    <user id="12ab34cd5-6ef7-8ab9-0cd1-2ef34ab56cd" name="Laura"
        siteRole="Unlicensed"  language="en-GB" locale="GB" />
    <user id="9a8a7b6b5-c4c3-d2d1-e0e9-a8a7b6b5b4b" name="Michelle"
        siteRole="ExplorerCanPublish" language="en-GB" locale="GB" />
    <user id="9f8e7d6c5-b4a3-f2e1-d0c9-b8a7f6e5d4c" name="Susan"
        siteRole="Explorer" language="en-GB" locale="GB" />

  </users>
</tsResponse>

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Unlicensed&sort=name:asc" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

This example includes a filter to return the users whose site role is Unlicensed and specifies that the results should be sorted by the name value.

Query Groups

Returns a list of groups on the specified site, with optional parameters for specifying the paging of large results.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/groups

GET /api/api-version/sites/site-id/groups?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/groups?filter=filter-expression

GET /api/api-version/sites/site-id/groups?sort=sort-expression

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the groups.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of groups to return. You can filter on predefined fields such as name. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <groups>
    <group id="group-id"
      name="group-name">
        <domain name="domain-for-group" />
    </group>
    <group id="group-id"
      name="group-name">
        <domain name="domain-for-group" />
		<import source="import-source"
		  domainName="active-directory-domain-name"
		  siteRole="minimum-site-role"
		  grantLicenseMode="license-mode" />
	</group>
    ... additional groups ...
  </groups>
</tsResponse>

If the group was imported from Active Directory, the name attribute of the <domain> element contains the group's Active Directory domain. For a group that uses local authentication, the value of that attribute is local.

The response body for a local group that has enabled onLogin for its grant license mode will have an import element with a domain name of local. Local groups with grant license mode unset, have no import element in their response.

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X GET -H "X-Tableau-Auth:e35Z608JMPHgZfVyJncnedlUeXSX8bmb"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="3"/>
  <groups>
    <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="All Users">
      <domain name="local"/>
    </group>
    <group id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="active-directory-group-import">
      <domain name="MYDOMAIN.net"/>
	  <import domainName="MYDOMAIN.net" siteRole="ExplorerCanPublish" grantLicenseMode="onLogin"/>
	</group>
    <group id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="local-group-license-on-login">
      <domain name="local"/>
      <import domainName="local" siteRole="ExplorerCanPublish" grantLicenseMode="onLogin"/>
    </group>
  </groups>
</tsResponse>

Query User On Site

Returns information about the specified user.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to get information for.

Request Body

None

Permissions

Using this method server administrators and site administrators can view user information directly or through the various ways that data is used throughourt Tableau. Use of this method by non-administrator users to view their own information depends on the visibility settings of a site. Using the Visibility Setting in the server UI, or the Create Site or Update Site methods, you can change user visibility settings of a Site. For more information, see Manage Site User Visibility(Link opens in a new window).

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
        name="user-name"
        siteRole="site-role"
        lastLogin="last-login-date"
        externalAuthUserId="authentication-id-from-external-provider"
		fullName="user-full-name"
		authSetting="auth-setting"
		language="language-code"
        locale="locale-code" />
  <domain name="user-domain" />
</tsResponse>

The lastLogin attribute value is returned as a date in UTC format (YYYY-MM-DDTHH:MM:SSZ).

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value represents an ID for the user for single sign-on (SSO) with an external identity provider. If the user is not configured to use external authentication, this value is an empty string.

(Tableau Server version 9.0.1/schema version 2.0.1 and later). If SAML is enabled, and the user was imported from Active Directory, the name attribute of the <domain> element contains the user's Active Directory domain.

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.
403 403133 Query user permissions forbidden The user does not have permissions to query user information for other users.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Alan"
    siteRole="ExplorerCanPublish"
    fullName="Alan Wang"
    authSetting="ServerDefault"
    lastLogin="2015-01-05T03:24:36Z"
	language="en-GB"
	locale="GB" />
</tsResponse>

Get Groups for a User

Gets a list of groups of which the specified user is a member.

URI

GET /api/api-version/sites/site-id/users/user-id/groups

GET /api/api-version/sites/site-id/users/user-id/groups?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
user-id The ID of the user whose group memberships are listed.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <groups>
    <group id="user-id" name="user-name" >
    	<domain name="group-domain-name"/>
	</group>
    <!--      . . . additional groups ...      -->
  </groups>
</tsResponse>

Version

Version 3.7 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 User not found The group ID in the URI doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/groups" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <groups>
    <group id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="All Users" >
	  <domain name="mydomain"/>
	</group>
	<group id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234" name="Researchers" >
	  <domain name="mydomain"/>
    </group>
  </groups>
</tsResponse>

Update Group

Updates a group in Tableau Server.

If the server is configured to use local authentication, the method lets you update the group name. If the server is configured to use Active Directory authentication, the method synchronizes the Tableau Server group with Active Directory.

During synchronization, the method updates the group in Tableau Server and modifies the set of users in the group to be the same as those in Active Directory. Users in Active Directory that are not in the group on Tableau Server are added to the group, and users in Tableau Server that are not in the Active Directory group are removed from the Tableau Server group. Users that are no longer in Active Directory at all are unlicensed.

If the update synchronizes with Active Directory, Tableau Server can perform the update either immediately (synchronously) or by using a background job (asynchronously). If Active Directory contains a large number of users, you should perform the synchronization process as a background job so that the process doesn't time out. By default, synchronizing with Active Directory is performed immediately (synchronously).

URI

PUT /api/api-version/sites/site-id/groups/group-id

PUT /api/api-version/sites/site-id/groups/group-id?asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to update.
AsJob-value A Boolean value that is used if you are importing from Active Directory. Set this value to true to synchronize with Active Directory as a background task, or set this value to false to synchronize immediately (synchronously). The default is false.

Note: This parameter has no effect if the server is configured to use local authentication.

Request Body

Updating a local group

<tsRequest>
  <group name="new-group-name"
	grantLicenseMode="license-mode"
	minimumSiteRole="minimum-site-role"/>
</tsRequest>

Updating an Active Directory group

<tsRequest>
  <group name="AD-group-name">
    <import source="ActiveDirectory" domainName="AD-domain"
      minimumSiteRole="minimum-site-role"
      grant-license-mode="license-mode"  />
  </group>
</tsRequest>

When the request body contains an <import> element, and if Tableau Server is configured to authenticate via Active Directory, the Update Group method synchronizes with Active Directory. If the server is configured to use local authentication, including an <import> element has no effect.

Attribute Values

new-group-name The new name for the group.
AD-group-name The name of the Active Directory group to synchronize with.
AD-domain The domain for the Active Directory group.
minimum-site-role

Required if an import element or grantLicenseMode attribute are present in the request. The site role assigned to users who are imported from Active Directory or granted a license automatically using the grant license on-sync or on-login mode.

If the requested user name matches an existing user in the group, the user either retains their existing role or are granted the one specified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to is imported from Active Directory or local.

Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows.

  1. Unlicensed
  2. Viewer
  3. Explorer
  4. ExplorerCanPublish
  5. Creator
  6. SiteAdministratorExplorer

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

license-mode

Optional. The mode for automatically applying licenses for group members. When the mode is onLogin, a license is granted for each group member when they login to a site.

For local groups, the mode can be either onLogin or unset. If the attribute is omitted during an update, the group will use the license grant mode configured prior to the update. A local group configured to use onLogin can switch the mode to unset by updating the group using:

minimumSiteRole="UNLICENSED"

For groups that import an Active Directory domain, the grantLicenseMode can be updated to either onSync or onLogin. If the attribute is omitted during an update, the group will use the license grant mode configured prior to the update.

The minimum role granted to users through grantLicenseMode is specified in the minimumSiteRole attribute of the import element. If that role has less permissions than an existing role assigned to the user, then the user's permissions remain unchanged.

Permissions

This method can only be called by server administrators or site administrators.

Response Code

200 (immediate update)

202 (background update)

Response Body

Updating a local group:

<tsResponse>
  <group id="new-group-id"
	name="group-name"
	grantLicenseMode="license-mode"
	minimumSiteRole="minimum-site-role" />
</tsResponse>

Updating an Active Directory group:

<tsResponse>
  <group id="new-group-id"
	name="group-name" />
 	  <import domainName="active-directory-domain-name”
	    minimumSiteRole="default-site-role"
	    grantLicenseMode="license-mode" />
	</group>
</tsResponse>

Background update:

<tsResponse>
  <job id="job-id"
    mode="Asynchronous"
    type="GroupSync"
    progress="0"
    createdAt="time-job-created" />
</tsResponse>

If the operation is performed asynchronously, the response body contains a <job> element that includes a job ID. You can check the status of the operation by using the Query Job method, which returns status information about the job. A typical approach is to periodically call Query Job method and get the value of the progress attribute from the response body; when this value returns 100, the import process is complete.

Version

Version 3.9 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.
403 400013 Invalid site role

The value of the minimumSiteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

403 400019 Malformed import element If the body includes an <import> element, it must contain a source, domainName, and minimumSiteRole attribute. If any of these attributes are missing, the element is malformed. In addition, the source attribute must have a value of ActiveDirectory; otherwise the element is malformed.
403 403011 ActiveDirectory not configured The request body contains an <import> element is included, but Tableau Server is configured for local authentication.
403 403020 Imported group name update forbidden The request body contains an <import> element and the value of the name attribute of the <group> element in the request body is different from the name of the group imported into Tableau Server as referenced by the group-id value in the URI.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing site.
404 404016 Domain not found The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory.
404 404017 Active Directory group not found The request body includes an <import> element, but no group with the name specified in the <group> element exists in Active Directory.
405 405000 Invalid request method Request type was not PUT.
409 409009 Group name conflict The group name in the request is already in use in the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

For more information, see Handling Errors.

Update User

Modifies information about the specified user.

If Tableau Server is configured to use local authentication, you can update the user's name, email address, password, or site role.

If Tableau Server is configured to use Active Directory for authentication, you can change the user's display name (full name), email address, and site role. However, if you synchronize the user with Active Directory, the display name and email address will be overwritten with the information that's in Active Directory.

For Tableau Online, you can update the site role for a user, but you cannot update or change a user's password, user name (email address), or full name.

URI

PUT /api/api-version/sites/site-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to update.

Request Body

<tsRequest>
 <user fullName="new-full-name"
    email="new-email"
    password="new-password"
    siteRole="new-site-role"
    authSetting="new-auth-setting" />
</tsRequest>

Attribute Values

Any combination of the elements inside the <user> element is valid. Only those elements present will result in updates to their values for the user. If no elements are present, the update will not take effect.

new-full-name (Optional) The new name for the user. Users can change names without affecting the groups they belong to. Tableau Server only. Not available in Tableau Online.
new-email (Optional) The new email address for the user. Tableau Server only. Not available in Tableau Online.
new-password (Optional) The new password for the user. Tableau Server only. Not available in Tableau Online.
new-site-role

The new site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Note: Only a user in the ServerAdministrator site role can use the REST API to add or remove another user from the ServerAdministrator site role. Users in the ServerAdministrator site role can only be moved to the Creator site role if one or more Creator licenses have been activated on the server; otherwise these users can only be moved to the Publisher site role. This method only supports the ServerAdministrator site role in version 2.8 and later.

new-auth-setting

(Optional) The authentication type for the user.

(For Tableau Server: This attribute only applies when adding users to sites with site-specific SAML enabled in settings.)

You can assign the following values for this attribute:

Permissions

This method can only be called by server administrators or site administrators. In addition, site administrators have some limitations in what changes they can make to users:

  • Site administrators cannot set the fullName value.
  • On Tableau Server, site administrators can change the email and password values only if the caller is a site administrator for all sites that the user is a member of. On Tableau Online, you cannot change a user's email or password.
  • Site administrators can change the siteRole value only if the site is configured to allow site administrators to add and remove site users. Site administrators on Tableau Online can change the siteRole value because they have permission to add and remove site users.

Response Code

200

Response Body

<tsResponse>
 <user name="user-name"
    fullName="new-full-name"
    email="new-email"
    siteRole="new-site-role"
    authSetting="new-auth-setting" />
</tsResponse>

Version

Version 1.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 400000 Invalid email address The email attribute does not contain a valid email address.
403 403009 Licensing update on self forbidden A user cannot update their own licensing role.
403 403009 Guest update forbidden The Guest user is a special user and cannot be updated.
400 400013 Invalid site role

The value of the siteRole attribute must be Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

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.
405 405000 Invalid request method Request type was not PUT.
409 409000 User conflict The user with the specified name is already registered on the site in the same domain.
409 409014 Licensing conflict The request is attempting to update the user to a licensing role that has insufficient capacity.

For more information, see Handling Errors.

Remove User from Group

Removes a user from the specified group.

URI

DELETE /api/api-version/sites/site-id/groups/group-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to remove the user from.
user-id The ID of the user to remove.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

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 400032 Deletion failed A problem arose that prevented the user from being removed from the site.
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 name in the URI doesn't correspond to an existing user.
404 404012 Group not found The group name in the URI doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) if the user is successfully removed from the group. The HTTP response code is 204 if the delete operation succeeded.

Remove User from Site

Removes a user from the specified site. If a user still owns content (assets) on Tableau Server, the user cannot be deleted unless the ownership is reassigned first.

If a user is removed from all sites that the user is a member of, the user is deleted.

URI

DELETE /api/api-version/sites/site-id/users/user-id

DELETE /api/api-version/sites/site-id/users/user-id?mapAssetsTo=new-user-id

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to remove.
mapAssetsTo Optional. When included in the URI path, the contents owned by the user being removed are transferred to another user.
new-user-id The ID of a user that receives ownership of contents of the user being remove.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

204

Response Body

None

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Deletion failed Some other problem arose that prevented the user from being removed from the site.
403 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.
405 405000 Invalid request method Request type was not DELETE.
409 409003 User asset conflict The specified user still owns content on Tableau Server and cannot be deleted.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) if the user is successfully removed from the site. The HTTP response code is 204 if the delete operation succeeded.

Delete Group

Deletes the group on a specific site. Deleting a group does not delete the users in group, but users are no longer members of the group. Any permissions that were previously assigned to the group no longer apply.

Note: You cannot delete the All Users group.

URI

DELETE /api/api-version/sites/site-id/groups/group-id

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
group-id The ID of the group to delete.

Request Body

None

Permissions

This method can be called by site administrators.

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
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group or the group is not part of the specified site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.


Thanks for your feedback! There was an error submitting your feedback. Please try again.