Tableau REST API Help

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

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

Parameter Values

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

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

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)

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 @bulk-add-user-to-group.xml

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>

URI

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

Parameter Values

Request Body

<tsRequest>
  <user name="user-name"
        siteRole="site-role"
        authSetting="auth-setting"
		identityPoolName="identity-pool-name"
		idpConfigurationId="idp-configuration-id" />
</tsRequest>

{
	"user": {
	   "name":"user-name",
	   "siteRole":"site-role",
	   "authSetting":"auth-setting",
	   "identityPoolName":"identity-pool-name",
	   "idpConfigurationId":"idp-configuration-id"
	 }
}

Attribute Values

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:users:create

Response Code

201

Response Body

<tsResponse>
  <user id="user-id"
   name="user-name"
   siteRole="site-role"
   authSetting="auth-setting"
   identityPoolName="identity-pool-name"
   idpConfigurationId="idp-configuration-id" />
</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

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>

URI

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

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

Parameter Values

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

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

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

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>

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

Request Body

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

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

Request Attributes

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

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

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

Errors

For more information, see Handling Errors.

URI

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

Parameter Values

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

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:delete

Response Code

204

Response Body

None

Version

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

Errors

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.

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

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

For more information, see Handling Errors.

URI

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

Parameter Values

Request Body

Because this method involves a file that is external to Tableau a multi-part request is required. For more information on multi-part 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

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

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

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

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="
  }
}

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

Request Body

None

Permissions

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

Required scope for JWT authorization

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

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau: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

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>

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

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

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

{
  "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

For more information, see Handling Errors.

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

Request Body

None

Permissions

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

Required scope for JWT authorization

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

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau: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 siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value is returned for Tableau 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

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>

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

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

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: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"
	   idpConfigurationId="idp-configuration-id"
      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"
	   idpConfigurationId="idp-configuration-id"
      language="language-code"
      locale="locale-code">
        <domain name="domain-name"/>
    </user>

  </users>
</tsResponse>

Notes:

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

• The externalAuthUserId value is returned for Tableau Cloud only ; 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.

• 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 Connect enabled.

• Starting in API 3.24, idpConfigurationId indicates the authentication method assigned to the user in Tableau Cloud only.

Version

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

Errors

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" idpConfigurationId="00000000-0000-0000-0000-0000000000">
        <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" idpConfigurationId="b2207590-024c-4a6e-ac4a-eca6eefabb2e">
        <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.

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

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

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

{
  "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

For more information, see Handling Errors.

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

Request Body

None

Permissions

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

Required scope for JWT authorization

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

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau: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

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>

URI

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

Parameter Values

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

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: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"
		idpConfigurationId="idp-configuration-id"
  <domain name="user-domain" />
</tsResponse>
        

Notes:

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

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

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

• In Tableau Server version 9.0.1 or API 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.

• Starting in API 3.24, idpConfigurationId indicates the authentication configuration assigned to the user in Tableau Cloud only.

Version

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

Errors

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"
	idpConfigurationId="00000000-0000-0000-0000-0000000000" />
</tsResponse>

URI

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

URI Parameter Values

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

For more information, see Handling Errors.

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

Request Body

None

Permissions

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

Required scope for JWT authorization

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

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:users:delete

Response Code

204

Response Body

None

Version

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

Errors

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.

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

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)

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

204

Response Body

None

Version

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

Errors

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.

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

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

minimumSiteRole="UNLICENSED"

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

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

For more information, see Handling Errors.

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

Request Body

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

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

Attribute Values

Response Code

200

Response Body

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

{
  "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

For more information, see Handling Errors.

URI

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

Parameter Values

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"
	idpConfigurationId="idp-configuration-id" />
</tsRequest>

{
	"user": {
	   "fullName":"new-full-name",
	   "email":"new-email",
	   "password":"new-password",
	   "siteRole":"new-site-role",
	   "authSetting":"new-auth-setting",
	   "identityPoolName":"identity-pool-name",
	   "idpConfigurationId":"idp-configuration-id"
	 }
}

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.

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"
	identityPoolName="identity-pool-name"
	idpConfigurationId="idp-configuration-id" />
</tsResponse>
        

Version

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

Errors

For more information, see Handling Errors.

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

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

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.