Users and Groups Methods

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

Groups (groups of users)

Create a local group of users for a site or import users to a new local group from Active Directory
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
Bulk add or remove users
Set minimum site role and enable on-demand access (Tableau Cloud only)

Group Sets (sets of groups)

Create a group set
Get a filtered, sorted list of group sets
Update a group set
List, add, or delete groups of a group set
Delete a group set

Site Users (users of a site)

Get a filtered, sorted list of users of a site
Get or update the details of a user of a site
Add or delete a user of a site
Import users and set their user properties from a .csv file
Delete a group, or a list of users in a .csv file, from a site
Download user credentials for migrating users to another site
Upload user credentials users migrated to another site

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

Add Group to Group Set

Adds group to a group set.

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets: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

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

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 unique ID of the site asset.
group-set-id	The unique ID of the group set you want to add the group to.
group-id	The unique ID of the group you want to add to the group set.

Request Body

None

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.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
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 request body doesn't correspond to an existing group.
409	409120	Group set not found	The group set ID in the request body doesn't correspond to an existing group.

For more information, see Handling Errors.

Add User to Group

Adds a user to the specified group.

Beginning in API 3.21, you can bulk add users to a group by specifying multiple user IDs.

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.24`. 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

Add a single user to a group

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

Bulk add users to a group (beginning in API 3.21)

<tsRequest>
  <users>
	<user id="user-id1" />
	<user id="user-id2" />
	<user id="user-id2" />
  </users>
</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.

Beginning in API 3.21, you can bulk add users to a group by specifying multiple user IDs.

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:groups:update

Response Code

200

Response Body

Add a single user to a group

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

Bulk add users to group (beginning in API 3.21)

<tsResponse>
  <users>
	<user id="user-id"
     name="user-name"
     siteRole="site-role" />
	<user id="user-id"
	 name="user-name"
	 siteRole="site-role" />
  </users>
</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

Add a single user to a group

curl "http://MY-SERVER/api/3.24/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>
  <users 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>

Bulk add users to a group (beginning in API 3.21)

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

<tsRequest>
  <users>
	<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
	<user id="1z4e8n7q-6t8t-8f8e-7d7c-1b1a2f2d2e2d" />
  </users>
</tsRequest>

Example response:

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

Add User to Site

Adds a user to Tableau Server or Tableau 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 Cloud, the name of the user must be the email address that is used to sign in to Tableau Cloud. After you add a user, Tableau Cloud 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.24`. 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"
		identityPoolName="identity-pool-name" />
</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 Cloud, 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 Cloud: The user-name is the email address that the user will use to sign in to Tableau Cloud. When you add a user to the site, Tableau Cloud 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).
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: `SAML` - The user signs in using the identity provider (IdP) configured for the site. For Tableau Cloud configuration, see Enable SAML Authentication on a Site(Link opens in a new window). For Tableau Server, see Configure Site-Specific SAML(Link opens in a new window). `OpenID` - Tableau Cloud only the user signs in using Google, Salesforce, or their OpenID provider credentials. In Tableau Cloud authentication settings, `OpenID` corresponds to Google, Salesforce, or OIDC configuration. `TableauIDWithMFA` - Tableau Cloud only: The user signs in using a combination of TableauID credentials and a registered verification method. For more information, see About multi-factor authentication and Tableau Cloud(Link opens in a new window). `ServerDefault` - The user signs in using the default authentication method that's set for the server. For Tableau Cloud, if Tableau hasn't updated your site to require Tableau with MFA yet, you can continue to use this authentication type on a temporary basis. The `ServerDefault` value corresponds to TableauID in authentication settings. For Tableau Server, the SAML(Link opens in a new window) Server help page describes default authentication options.
identity-pool-name	(Optional, Tableau Server only) When identity pools are configured, the name of the identity pool. Starting in API 3.19, include the identity pool name when identity pools are configured and you need to add a user to an identity pool that uses the local identity store and OIDC authentication. For more information, see Identity Pools Methods.

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).

tableau:users:create

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.24/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	400003	Bad request	The user authentication setting `ServerDefault` is not supported for you site. Try again using `TableauIDWithMFA` instead.
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.24/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>

Create Group

Creates a group on Tableau Server or Tableau Cloud site.

If Tableau Server is configured to use Active Directory for authentication, this method can create a group 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.

For Tableau Server, 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 (Tableau Server only) immediately, the response body contains the name and ID of the new group. If you import an Active Directory group (Tableau Server only) 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.24. 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.

This attribute is available for Tableau Server only.

Request Body

Creating a local group

<tsRequest>
  <group name="new-tableau-server-group-name"
   minimumSiteRole="minimum-site-role"
   ephemeralUsersEnabled="on-demand-access"/>
</tsRequest>

When the request is to create a local group and minimumSiteRole is specified, users are granted a license using the grant license on-login mode by default.

Importing a group from Active Directory (Tableau Server only)

<tsRequest>
  <group name="active-directory-group-name" >
    <import source="ActiveDirectory"
      domainName="active-directory-domain-name"
      grantLicenseMode="license-mode"
      siteRole="minimum-site-role"/>
  </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 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. If Tableau Server or Tableau Cloud site is configured to use local authentication, including an <import> element has no effect.

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. This attribute is available for Tableau Server only.
active-directory-domain-name	The domain of the Active Directory group to import. This attribute is available for Tableau Server only.
minimum-site-role	Required if an import element or grantLicenseMode attribute are present in the request. For Tableau Server, 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 (Tableau Server only) or local. Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows. Unlicensed Viewer Explorer ExplorerCanPublish Creator SiteAdministratorExplorer SiteAdministratorCreator Note: You cannot use the REST API to set a user to be a Tableau Server administrator (ServerAdministrator site role).
license-mode	The mode for automatically applying licenses for group members. When the mode is onLogin, a license is granted for each group member when they log in 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. 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.
on-demand-access	Optional. A boolean value that is used to enable on-demand access for embedded Tableau content when the Tableau Cloud site is licensed with Embedded Analytics(Link opens in a new window) usage-based model. Set to true to enable the capability for the group or set to false to disable the capability for the group. For more information about on-demand access, see one of the following topics in the Tableau Cloud Help: On-demand access using connected apps with direct trust(Link opens in a new window) or On-demand access using connected apps with OAuth 2.0 trust(Link opens in a new window). This attribute is available for Tableau Cloud only starting from API version 3.21 (October 2023).

Permissions

This method can only be called by Tableau Server administrators or Tableau Cloud site admins.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:groups:create

Response Code

201, for creating a local group and for importing immediately

202, for importing using a background process

Response Headers

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

Response Body

Creating a local group:

<tsResponse>
  <group id="new-group-id"
	name="group-name"
	minimumSiteRole="minimum-site-role"
	ephemeralUsersEnabled="true" />
	<import domainName="local" siteRole="default-site-role" grantLicenseMode="license-mode" />
  </group>
</tsResponse>

Creating a group and importing from Active Directory immediately (Tableau Server only):

<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 minimumSiteRole or 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	Active Directory 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.24/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" ephemeralUsersEnabled="true" />
</tsRequest>

Response header:

Location: /api/3.24/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" ephemeralUsersEnabled="true"/>
</tsResponse>

Example: Active Directory Group

curl "http://MY-SERVER/api/3.24/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.24/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>

Create Group Set

Creates a group set with a specified name.

Note: You can't use this method to populate the group set with groups. After you create a group set and its ID is available, you can add a group to the group set by calling Add Group to Group Set.

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:create 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-id/groupsets

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-id	The ID of the site to create the group in.

Request Body

XML

Copy

<tsRequest>
  <groupSet name="newGroupSet" />
</tsRequest

JSON

Copy

{
  "groupSet": {
    "@name": "marketing-group"
  }
}

Request Attributes

name

(Required) Name of the new group set.

cURL Request Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/" --header "Content-Type: application/xml" --header "X-Tableau-Auth: YqB9_MHoTHO26HGsFBFEBg|bQDOIH4MsqFGvUDYTrRYh633vrZHBt6d|a946d998-2ead-4894-bb50-1054a91dcab3" --data "<tsRequest> <groupSet name='marketing-group' /> </tsRequest>"

Response Code

201, for creating a group set.

Response Body

Copy

<tsRequest>
  <groupSet id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234" 
    name="marketing-group" 
    groupCount="0" />
</tsRequest>

Copy

{
  "groupSet": {
    "id": "4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234",
    "name": "marketing-group",
    "groupCount": "0"
  }
}

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 minimumSiteRole or siteRole attribute must be SiteAdministratorCreator or SiteAdministratorExplorer.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	The request type wasn’t POST.
409	409121	Group set name conflict	The group set name in the request already belongs to another group set. For the purpose of uniqueness checks, group set names are case-insensitive.

For more information, see Handling Errors.

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.24`. 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.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:groups: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
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.24/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.

Delete Group Set

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

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:delete 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

DELETE /api/api-version/sites/site-id/groupsets/group-set-id

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-id	The ID of the site that contains the project.
group-set-id	The ID of the group set to delete.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/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.

Response Code

204

Response Body

None

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.
405	405000	Invalid request method	Request type wasn’t DELETE.
409	409120	Group set not found	The group set ID in the URI doesn't correspond to an existing group set or the group set isn’t part of the specified site.

For more information, see Handling Errors.

Delete Users from Site with CSV

Creates a job to remove a list of users, specified in a .csv file, from a site.

The .csv file should comply with the rules described in the CSV Import File Guidelines(Link opens in a new window).

URI

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

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 users are being deleted from.

Request Body

Because this method involves a file that is external to Tableau a multipart request is required. For more information on multipart requests, See Importing CSV files with Multipart Requests(Link opens in a new window).

--boundary-string
Content-Disposition: form-data; name=\"tableau_user_delete\"; filename=\"users.csv\"
Content-Type: text/csv
--boundary-string--

Permissions

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

Response Code

204

Response Body

None

Version

Version 3.15 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 payload is missing or incomplete, or contains malformed XML.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

Example

curl -X POST \
http://10.108.21.238//api/3.15/sites/8aa3291f-1b5a-4f52-a3be-6512661f574d/users/delete \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'x-tableau-auth: AVjAKZb3SQimzoqyMmQXEg|9OSHQrwCXF83SIR2XCuDEK91AM7v3FZr' \
-F tableau_user_delete=@users.csv

Download User Credentials

Gets credentials for a user who is being migrated to another Tableau Cloud or Tableau Server site.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

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: This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available. 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/users/user-luid/retrieveSavedCreds

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.
user-luid	The LUID of the user whole credentials you want to download.

Request Body

<tsRequest>
  <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace>
  <destinationSiteLuid>d56023b5-8f8b-4241-aa74-8974ced85827</destinationSiteLuid>
  <destinationServerUrl>http://example.com</destinationServerUrl>
</tsRequest>

{
  "destinationSiteUrlNamespace": "site1",
  "destinationSiteLuid": "d56023b5-8f8b-4241-aa74-8974ced85827",
  "destinationServerUrl": "http://localhost"
}

Request Attributes

`destinationSiteUrlNamespace`	(Required) The site name on Tableau Cloud.
`destinationSiteLuid`	(Required) The site ID on Tableau Cloud.
`destinationServerUrl`	(Required) The destination Tableau Cloud URL.

cURL Request Example

curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/retrieveKeychain"  --header "Content-Type: application/xml"  --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86"  --data "<tsRequest>   <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace>    <destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid>   <destinationServerUrl>http://example.com</destinationServerUrl>  </tsRequest>"

Response Code

200

Response Body

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://tableau.com/api https://help.tableau.com/samples/en-us/rest_api/ts-api_3_24.xsd">
    <associatedUserLuidList/>
    <encryptedKeychainList>
        <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=
        <encryptedKeychain>
	</encryptedKeychainList>
</tsResponse>

{
  "associatedUserLuidList": [],
  "encryptedKeychainList": {
    "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y="
  }
}

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	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
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 POST.

For more information, see Handling Errors.

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.24`. 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.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:users:read

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="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.24/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>

Get Group Set

Returns information about the specified group set including ID, name, and member groups.

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:read 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

GET /api/api-version/sites/site-id/groupsets/group-set-id

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-id	The ID of the site that contains the group.
group-set-id	The ID of the group set you want information for.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/8cf3b6c1-839f-4eae-b41f-2144165193f2" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy

<tsResponse version-and-namespace-settings>
  <groupSet id="8cf3b6c1-839f-4eae-b41f-2144165193f2">
    <group id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"  
      name="All Users"
      groupCount="2">
    </group>
    <group id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234" 
      name="Researchers" >
    </group>
  </groupSet>
</tsResponse>

Copy

{
  "groupSet": {
    "@id": "8cf3b6c1-839f-4eae-b41f-2144165193f2",
    "group": [
      {
        "@id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d",
        "@name": "All Users",
        "@groupCount": "2"
      },
      {
        "@id": "4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234",
        "@name": "Researchers"
      }
    ]
  }
}

Version

Version 3.22 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.
405	405000	Invalid request method	The request type wasn’t GET.
409	409120	Group set not found	The group set ID in the request body doesn't correspond to an existing group set.

For more information, see Handling Errors.

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.24`. 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.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:groups:read

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 externalAuthUserId value is returned for Tableau Cloud; 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.24/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.24`. 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.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:users:read

Response Code

200

Response Body

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

  </users>
</tsResponse>

Note: The authSetting attribute is only returned if you are using Tableau Server with site-specific SAML enabled, or Tableau Cloud 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.24/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 email="alex@example.com"
      id="9f9e9d9c8-b8a8-f8e7-d7c7-b7a6f6d6e6d"
      fullName="Alex Smith" name="Alex"
      siteRole="Viewer" language="en-GB" locale="GB">
        <domain name="tsi.lan" />
    </user>
    <user email="jannaj@example.org"
      id="12ab34cd5-6ef7-8ab9-0cd1-2ef34ab56cd"
      fullName="Janna Johnson" name="Janna"
      siteRole="Unlicensed"  language="en-GB" locale="GB" >
        <domain name="tsi.lan" />
    </user>
    <user email="fred.zuzuki@example.net"
      id="9a8a7b6b5-c4c3-d2d1-e0e9-a8a7b6b5b4b"
      fullName="Fred Suzuki" name="Fred"
      siteRole="ExplorerCanPublish" language="en-GB" locale="GB">
        <domain name="tsi.lan" />
    </user>

    ... more users ...
  </users>
</tsResponse>

curl "http://MY-SERVER/api/3.24/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.

Import Users to Site from CSV

Creates a job to import the users listed in a specified .csv file to a site, and assign their roles and authorization settings.

The .csv file should comply with the rules described in the CSV Import File Guidelines(Link opens in a new window).

URI

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

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 unique ID of the site asset.

Request Body

--boundary-string
Content-Disposition: name="tableau_user_import"
Content-Type: file
path_to_csv
--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <user
    name="user-name
	authSetting="auth-setting" />
  <!--    more users    -->
</tsRequest>
--boundary-string--

A request-payload without user name or authSetting is valid, but must present in the request in the form: <tsRequest><user /></tsRequest>.

Attribute Values

path-to-csv	The filepath to the .csv list users to be imported.
user-name	(Optional) 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 Cloud, 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 Cloud: The user-name is the email address that the user will use to sign in to Tableau Cloud. When you add a user to the site, Tableau Cloud sends an email invitation. The user can click the link in the invitation to sign in and update their full name and password.
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: `SAML` - The user signs in using the identity provider (idP) configured for the site. For Tableau Cloud configuration, see Enable SAML Authentication on a Site(Link opens in a new window). For Tableau Server, see Configure Site-Specific SAML(Link opens in a new window). `ServerDefault` - The user signs in using the default authentication method that's set for the server. For Tableau Cloud ServerDefault corresponds to TableauID in authentication settings. For Tableau Server, the SAML(Link opens in a new window) Server help page describes default authentication options. `OpenID` - Tableau Cloud only the user signs in using Google or Salesforce credentials. In Tableau Cloud authentication settings, `OpenID` corresponds to selected identity provider, Google or Salesforce. `TableauIDWithMFA` - Tableau Cloud only: The user signs in using a combination of TableauID credentials and a registered verification method. For more information, see About multi-factor authentication and Tableau Cloud(Link opens in a new window). Assigning user auth settings with this method The request payload enables you to set auth settings for individual users, or all users in the .csv file. To prevent the payload from having any impact on auth settings, omit the `name` and `authSetting` attributes of the `user` object: `<tsrequest><user /></tsrequest>`. To set the default auth settings for all users being imported, omit the `name` attribute and specify the `authSetting` attribute of the `user` object: `<tsRequest><user authSetting="OpenID"/><tsRequest>` If the auth setting for a user is defined in both the imported .csv and in a request payload, the setting in the .csv will take precident. If no auth setting is defined for a user in either the .csv and the request payload, then the default setting of the site is assigned.
isVerbose	Tableau Cloud only When set to `false`, this method only returns the top three errors in a batch of users. When set to `true`, the method displays a full list of errors during CSV upload. Available in REST API 3.22 (Tableau Cloud February 2024)

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201 Created

Version

REST API version 3.15 and later. For more information, see REST API and Resource Versions.

Response Body

<tsResponse>
  <job id="job-luid"
	mode="Asynchronous"
	type="UserImport"
	progress="progress-status-code"
	createdAt="created-date"
  finishCode="job-finish-status-code" /e>
</tsResponse>

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request payload is missing or incomplete, or contains malformed XML.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

Example

curl -X POST \
http://10.108.21.238//api/3.15/sites/8aa3291f-1b5a-4f52-a3be-6512661f574d/users/import \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'x-tableau-auth: AVjAKZb3SQimzoqyMmQXEg|9OSHQrwCXF83SIR2XCuDEK91AM7v3FZr' \
-F tableau_user_import=@users.csv \
-F 'request_payload=<tsRequest><user name="jdoe" authSetting="OpenID"/></tsRequest>'

Response

<tsResponse>
<job id=">c8c2ee06-624f-4c11-a88d-8c9ec3b5813d"
  mode="Asynchronous"
  type="UserImport"
  progress="0"
  createdAt="2022-02-10T18:46:04Z"
  finishCode="1" />
</tsResponse>

List Group Sets

Lists all group sets matching optional filter and ordered by optional sort expression.

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.

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:read 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

GET /api/api-version/sites/site-id/groupsets?[resultlevel=[members,local]

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

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

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

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-id	The ID of the site that contains the group sets.
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 group sets 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 group set information is returned. If you don’t 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

cURL Request Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets&[resultlevel=[members,local]]" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="3"/>
  <groupSets>
    <groupSet id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="All Users" groupCount="1">
      <group id="gs-1" name="group-one"/>
    </groupSet>
    <groupSet id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="active-directory-group-import">
      <group id="gs21" name="group-two"
    </groupSet>
    <groupSet id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="local-group-license-on-login">
      <group id="gs-3" name="group-three"
    </groupSet>
  </groupSets>
</tsResponse>

Copy

{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "3"
  },
  "groupSets": [
    {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "All Users",
      "groupCount": "1",
      "group": {
        "id": "gs-1",
        "name": "group-one"
      }
    },
    {
      "id": "9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b",
      "name": "active-directory-group-import",
      "group": {
        "id": "gs21",
        "name": "group-two"
      }
    },
    {
      "id": "7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6",
      "name": "local-group-license-on-login",
      "group": {
        "id": "gs-3",
        "name": "group-three"
      }
    }
  ]
}

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter isn’t 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 isn’t 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	The request type wasn’t GET.
409	409120	Group set not found	The group set ID in the URI doesn't correspond with an existing group set.

For more information, see Handling Errors.

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.24`. 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.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:groups:read

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 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.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/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.24`. 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 throughout 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).

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:users:read

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 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.24/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>

Remove Group from Group Set

Removes a group from the specified group set.

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets: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

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

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-id	The ID of the site that contains the group set.
group-set-id	The ID of the group set to remove the group from.
group-id	The ID of the group to remove.

Request Body

None

Example

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

Response Body

None

Errors

HTTP status	`error` Code	Condition	Details
400	400032	Deletion failed	A problem arose that prevented the group from being removed from the group set.
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 wasn’t DELETE.
409	409120	Group set not found	The group set ID in the URI doesn't correspond to an existing user.

For more information, see Handling Errors.

Remove User from Site

Removes a user from the specified site. The user will be deleted if they do not own any other assets other than subscriptions. If a user still owns content (assets) on Tableau Server, the user cannot be deleted unless the ownership is reassigned first.

You can’t remove a user from the server if they own content on any site on that server. You can remove a user from a site if they no longer own content on the site.

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.24`. 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. If the user owns subscriptions and no mapAssetsTo is provided, the value of the owner is changed to unknown user. If a user owns only subscriptions, you can delete them from either server or site without having to set mapAssetsTo a different user. If a user owns only subscriptions, you can delete the user from the server or site without setting this value. Note: Even though both server administrators and site administrators can call this method, only server administrators can use the mapAssetsTo parameter to reassign content ownership. Site administrators can't use this parameter value. You must be a server administrator to remove a user who still owns content on Tableau Server.
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.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:users:delete

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.24/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.

Remove User from Group

Removes a user from the specified group.

Beginning in API 3.21, you can bulk remove users from a group by specifying multiple user IDs.

URI

Remove a single user from a group

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

Bulk remove users from a group (beginning in API 3.21)

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

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 group.
group-id	The ID of the group to remove the user from.
user-id	The ID of the user to remove.

Request Body

Remove a single user from a group

None

Bulk remove users from a group (beginning in API 3.21)

<tsRequest>
  <users>
	<user id="user-id1" />
	<user id="user-id2" />
	<user id="user-id2" />
  </users>
</tsRequest>

Attribute Values (bulk remove users only)

user-id

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

Beginning in API 3.21, you can bulk remove users from a group by specifying multiple user IDs.

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).

tableau:groups:update

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

Remove a single user from a group

curl "http://MY-SERVER/api/3.24/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"

Bulk remove users from a group (beginning in API 3.21)

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @bulk-remove-users-from-group.xml

Content of bulk-remove-users-from-group.xml:

<tsRequest>
  <users>
	<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
	<user id="1z4e8n7q-6t8t-8f8e-7d7c-1b1a2f2d2e2d" />
  </users>
</tsRequest>

Example response:

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

Update Group

Updates a group on a Tableau Server or Tableau Cloud site.

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

During synchronization, the method updates the group 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 that are not in the Active Directory group are removed from the 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.24`. 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. This attribute is available for Tableau Server only.

Request Body

Updating a local group

<tsRequest>
  <group name="new-group-name"
    minimumSiteRole="minimum-site-role"
    ephemeralUsersEnabled="on-demand-access" />
</tsRequest>

When the request is to update a local group and minimumSiteRole is specified, users are granted a license using the grant license on-login mode by default.

Updating an Active Directory group (Tableau Server only)

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

When the request body contains an <import> element, and if Tableau Server or Tableau Cloud site is configured to authenticate via Active Directory, the Update Group method synchronizes with Active Directory. If Tableau 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. This attribute is available for Tableau Server only.
AD-domain	The domain for the Active Directory group. This attribute is available for Tableau Server only.
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 (Tableau Server only) 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 (Tableau Server only) or local. Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows. Unlicensed Viewer Explorer ExplorerCanPublish Creator SiteAdministratorExplorer SiteAdministratorCreator Note: You cannot use the REST API to set a user to be a Tableau 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 log in 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 (Tableau Server only), 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 siteRole 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.
on-demand-access	Optional. A boolean value that is used to enable on-demand access for embedded Tableau content when the Tableau Cloud site is licensed with Embedded Analytics(Link opens in a new window) usage-based model. Set to true to enable the capability for the group or set to false to disable the capability for the group. For more information about on-demand access, see one of the following topics in the Tableau Cloud Help: On-demand access using connected apps with direct trust(Link opens in a new window) or On-demand access using connected apps with OAuth 2.0 trust(Link opens in a new window). This attribute is available for Tableau Cloud only starting from API version 3.21 (October 2023).

Permissions

This method can only be called by Tableau Server administrators or Tableau Cloud site admins.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

tableau:groups:update

Response Code

200 (immediate update)

202 (background update)

Response Body

Updating a local group:

<tsResponse>
  <group id="new-group-id"
	name="group-name"
	ephemeralUsersEnabled="true"
	minimumSiteRole="minimum-site-role">
         <import domainName="local" siteRole="default-site-role" grantLicenseMode="license-mode"/>
</tsResponse>

Updating an Active Directory group (Tableau Server only):

<tsResponse>
  <group id="new-group-id"
	name="group-name">
 	  <import domainName="active-directory-domain-name”
           grantLicenseMode="license-mode"
	    minimumSiteRole="default-site-role" />
  </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 or siteRole 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 siteRole 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	Active Directory 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 Group Set

Updates a group set name on a Tableau Server or Tableau Cloud site.

Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets: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

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

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 group.
group-set-id	The ID of the group set to update.

Request Body

Copy

<tsRequest>
  <groupSet name="Researchers-one" />
</tsRequest>

Copy

{
  "groupSet": {
    "@name": "Researchers-one"
  }
}

Attribute Values

name	The new name for the group set.

Response Code

200

Response Body

Copy

<tsResponse>
  <groupSet id="group-set-id"
    name="Researchers-one"
    groupCount="2"/>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
        name="Internal"/>
      <group id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b"
        name="External"/>
  </groupSet>
</tsResponse>

Copy

{
  "groupSet": {
    "id": "group-set-id",
    "name": "Researchers-one",
    "groupCount": "2",
    "group": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "name": "Internal"
      },
      {
        "id": "9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b",
        "name": "External"
      }
    ]
  }
}

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 or 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.
405	405000	Invalid request method	The request type wasn’t PUT.
409	409120	Group set not found.	The group set ID in the request body doesn't correspond to an existing group set.
409	409121	Group set name conflict	The group set name in the request already belongs to another group set. For the purpose of uniqueness checks, group set 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 Cloud, 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.24`. 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"
	identityPoolName="identity-pool-name" />
</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 Cloud.
new-email	(Optional) The new email address for the user. Tableau Server only. Not available in Tableau Cloud.
new-password	(Optional) The new password for the user. Tableau Server only. Not available in Tableau Cloud.
new-site-role	The new site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, 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: `SAML` - The user signs in using the identity provider (idP) configured for the site. For Tableau Cloud configuration, see Enable SAML Authentication on a Site(Link opens in a new window). For Tableau Server, see Configure Site-Specific SAML(Link opens in a new window). `OpenID` - Tableau Cloud only: The user signs in using Google, Salesforce or OpenID provider credentials. `OpenID` corresponds to Google, Salesforce, or OIDC authentication configuration in Tableau Cloud authentication settings. `TableauIDWithMFA` - Tableau Cloud only: The user signs in using a combination of TableauID credentials and a registered verification method. For more information, see About multi-factor authentication and Tableau Cloud(Link opens in a new window). `ServerDefault` - The user signs in using the default authentication method that's set for the server. For Tableau Cloud, if Tableau hasn't updated your site to require Tableau with MFA yet, you can continue to use this authentication type on a temporary basis. The `ServerDefault` value corresponds to TableauID in authentication settings. For Tableau Server, the SAML(Link opens in a new window) Server help page describes default authentication options.
identity-pool-name	(Optional, Tableau Server only) When identity pools are configured, the name of the identity pool. Starting in API 3.19, include the identity pool name when identity pools are configured and you need to add a user to an identity pool that uses the local identity store and OIDC authentication. For more information, see Identity Pools Methods.

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 Cloud, 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 Cloud 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.
400	400003	Bad request	The user authentication setting `ServerDefault` is not supported for you site. Try again using `TableauIDWithMFA` instead.
400	400012	Bad request	The user cannot be assigned the Unlicensed role because they are still a member of a group that has a minimum site role set.
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.

Upload User Credentials

Uploads user credentials to a site on a destination Tableau Cloud or Tableau Server.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

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: This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available. 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

PUT /api/api-version/sites/site-luid/users/user-luid/uploadSavedCreds

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.
user-luid	The LUID of the user whose credentials you want to upload.

Request Body

<tsRequest>
  <associatedUserLuidMapping/>
  <encryptedKeychainList>
    <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=
    <encryptedKeychain>
  </encryptedKeychainList>
</tsRequest>

{
  "associatedUserLuidMapping": [],
  "encryptedKeychainList": {
    "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y="
  }
}

Request Attributes

`associatedUserLuidMapping`	(Required) The user IDs from the source site mapped to destination site user IDs.
`encryptedKeychainList`	(Required) List of encrypted keychains from the source Tableau Server.

cURL Request Example

curl --location --request GET "https://example.com/api/3.24/sites/a946d998-2ead-4894-bb50-1054a91dcab3/users/6ae4a163-d073-4ab2-9668-954bab4b029e/uploadSavedCreds"  --header "Content-Type: application/json"  --data "<associatedUserLuidMapping/>     <encryptedKeychainList>         <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=         <encryptedKeychain> 	</encryptedKeychainList>"

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.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
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.

For more information, see Handling Errors.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help