Get Started Tutorial Part 3: Make a User Group and Give it Permissions


What is in part 3 of this tutorial?

This is part 3 of a 3-part tutorial to help you get started using the Tableau Server REST API. Steps on this page depend on completing the previous parts. We expect this part will take you about 20 minutes to complete.

Step 1: Manually add users to your site

You can control who gets access to your Tableau resources in several ways. In this tutorial, we demonstrate giving permissions for a group of users to access a workbook. Organizing permissions with groups is a best practice that makes managing permissions easier.

You can add users to your site with a variety of methods, including via the command line in a terminal or by integrating with Active Directory through SAML. To keep things simple for now, add some users to your site manually.

To add users to your site manually:

  • Go to the user page(Link opens in a new window) of your server and choose Add User.
  • Choose Enter email addresses, copy and paste the following list of emails, and then choose Import users. 
    Amanda@mycompany.com; Brian@mycompany.com; Christina@mycompany.com; Daniel@mycompany.com; Elizabeth@mycompany.com; Frank@mycompany.com; George@mycompany.com; Heather@mycompany.com

Step 2: Create a group in your site

A group allows you to centrally manage the permissions for multiple users. To create a group on your site, use the following URI and request body.

URI

Here is the model for the REST call to create a group:

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

Request body

The request body carries the name of the group that is posted to the site.

<tsRequest>
	<group name="new-tableau-server-group-name" />
</tsRequest>

Making a REST request to create a group

  • Using Postman - To use Postman to create a group:

    An example of the URI to create a group looks like:

    https://MY-SERVER/api/3.4/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups

      1. Open Postman and create a new request called Create Group and save it in your REST Tutorial Collection.
      2. Add the request body described in this section (see how it is done at Make a REST sign in request(Link opens in a new window)).
      3. Add URI with your server name and site id, and then make sure the verb is set to POST.
      4. Add the credentials token to the request header (see how it's done at Authentication of REST calls(Link opens in a new window)).
      5. Choose Send, then scroll down to view the response panel.

  • Using cURL - To use cURL to create a group:

    1. Paste your request body into a text editor such as Notepad or TextEdit and save it somewhere you will remember as a file named create-group.xml.

    2. Open a terminal window (Windows / Mac(Link opens in a new window)). At the command prompt, navigate to the directory where you saved create-group.xml. In the following command, replace MY_SERVER" with the name of your server, and the value of X-Tableau-Auth with the credentials token from your sign in response. Then run the command.

      cd /…/dir-containing-create-group-xml
curl "https://MY-SERVER/api/3.4/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d "@create-group.xml"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

If your request succeeds, the response body contains the group ID of the new group. 

<tsResponse xmlns="http://tableau.com/api"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://tableau.com/api
	http://tableau.com/api/ts-api-3.4.xsd">
	<group id="6fdc89d1-2ee0-457a-a116-e028d9c35722" name="new-group" />
</tsResponse>
Copy and save the group ID for following steps.

Step 3: Get IDs for users on your site

To add users to a group you need their IDs. Use the following URI to get the list of users with their IDs.

URI

Here is the model for the REST call to query users of a site:

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

Request body

None needed. Since this request is a query for a list of existing Tableau objects, you don't need to provide details in a request body. When you make a query request filter and sort(Link opens in a new window) the results to be returned.

Making a REST request to query users of a site

  • Using Postman - To use Postman to query users of a site:

    Here is an example of the URI to query users of a site.

    https://MY-SERVER/api/3.4/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users

      1. Open Postman and create a new request called Query Users and save it in your REST Tutorial Collection.
      2. Add the URI with your server name and site id, and then make sure the verb is set to GET.
      3. Add the credentials token to the request header (see how it's done at Authentication of REST calls(Link opens in a new window)).
      4. Choose Send, then scroll down to view the response panel.

  • Using cURL - To use cURL to get users of a site:

    1. Open a terminal window (Windows / Mac(Link opens in a new window)). In the following command, replace MY_SERVER" with the name of your server, and the value of X-Tableau-Auth with the credentials token from your sign in response. Then run the command.

      cd /…/dir-containing-create-group-xml
curl "https://MY-SERVER/api/3.4/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

If your request succeeds, the response body contains the metadata for each user, including their ID.

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.4.xsd">
	<pagination pageNumber="1" pageSize="100" totalAvailable="9"/>
		<users>
			<user id="1b526a10-048b-4d1d-96e7-e12ec7f46388"
			  name="you@myCompany.com" siteRole="SiteAdministratorCreator"
	    					    . . . more user metadata . . .  />
		  	<user id="1f7cef2e-29f2-4c33-9a17-02f48a401672"
		       name="amanda@mycompany.com" siteRole="ExplorerCanPublish"
		         			    . . . more user metadata . . .   />
		  	<!-- . . . more users . . . ->
		</users>
	</tsResponse>

Copy and save the user IDs for the next step.

Step 4:Add a user to a group

To add users to a group, use the following URI and request body. There are other methods to add multiple users to a group, but for simplicity we’ll use this one that allows adding only a single user at a time.

URI

Here is the model for the REST call to add a user to a group:

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

Request body

The request body provides the ID of the user to be added.

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

Making a REST request to add a user to a group

  • Using Postman - To use Postman to add a user to a group:

    An example of the URI to add a user looks like:

    https://MY-SERVER/api/3.4/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/34fb7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4f/users

      1. Open Postman and create a new request called Add User to Group and save it in your REST Tutorial Collection.
      2. Add the request body described in this section (see how it is done at Make a REST sign in request(Link opens in a new window)).
      3. Add URI with your server name and site id, and then make sure the verb is set to POST.
      4. Add the credentials token to the request header (see how it's done at Authentication of REST calls(Link opens in a new window)).
      5. Choose Send, then scroll down to view the response panel.

  • Using cURL - To use cURL to add a user to a group:

    1. Paste your request body into a text editor such as Notepad or TextEdit and save it somewhere you will remember as a file named add-user.xml.

    2. Open a terminal window (Windows / Mac(Link opens in a new window)). At the command prompt, navigate to the directory where you saved add-user.xml. Replace MY_SERVER" with the name of your server in the following command, and then run it as follows.

      cd /…/dir-containing-create-group-xml
curl "https://10ax.online.tableau.com/api/3.4/sites/c7b3099d-9e6d-44f1-8e05-d58d7fa97d4d/groups/6fdc89d1-2ee0-457a-a116-e028d9c35722/users" -X POST -H "X-Tableau-Auth:iiPAsjjzSo-mk7G-B6fBbQ|KGkRu6SnzWE7EOR72Dy2u4MkZgZxIAyL" -d "@add-users.xml"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

If your request succeeds, the response body confirms the ID of the added user. 

<tsResponse xmlns="http://tableau.com/api"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.4.xsd">
	<pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
		<user id="ebf29f91-eef3-4361-aca9-6850e12dd8f7" name="heather@mycompany.com"
			siteRole="Unlicensed" authSetting="ServerDefault"
		externalAuthUserId="3404345406-8354c3cb041040c8aedbcf81553860ec"/>
</tsResponse>

Step5: Give a group permissions to a workbook

To give users in a group permissions to a workbook, use the following URI and request body.

URI

Here is the model for the REST call to give a group of users permissions. The verb for this request is PUT because it updates existing permissions. Unlike POST, which creates a new resource, PUT requests have a body that contains the details of the update.

PUT /api/3.4/sites/site-id/workbooks/workbook-id/permissions

Request body

The request body carries the information about which permissions to grant what user group for which workbook.

<tsRequest>
	<permissions>
		<workbook id="workbook-id" />
		<granteeCapabilities>
			<group id="group-id" />
			<capabilities>
				<capability name="Read" mode="Allow" />
				<!-- ... additional capabilities ... -->
			</capabilities>
		</granteeCapabilities>
	</permissions>
</tsRequest>

Making a REST request to grant workbook permissions to a group

  • Using Postman - To use Postman to add group permissions

    An example of the URI to add a user looks like:

    https://MY-SERVER/api/3.4/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/34fb7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4f/permissions

      1. Open Postman and create a new request called Add Group Permissions and save it in your REST Tutorial Collection.
      2. Add the request body described in this section (see how it is done at Make a REST sign in request(Link opens in a new window)).
      3. Add URI with your server name and site id, and then make sure the verb is set to POST.
      4. Add the credentials token to the request header (see how it's done at Authentication of REST calls(Link opens in a new window)).
      5. Choose Send, then scroll down to view the response panel.

  • Using cURL - To use cURL to add group permissions:

    1. Paste your request body into a text editor such as Notepad or TextEdit and save it somewhere you will remember as a file named add-permissions.xml.

    2. Open a terminal window (Windows / Mac(Link opens in a new window)). At the command prompt, navigate to the directory where you saved add-permissions.xml. Replace MY_SERVER" with the name of your server in the following command, and then run it as follows.

      cd /…/dir-containing-add-permissions-xml
curl "https://10ax.online.tableau.com/api/3.4/sites/c7b3099d-9e6d-44f1-8e05-d58d7fa97d4d/workbooks/0d110ecf-b4d8-42c0-af2b-756be5677eeb/permissions" -X PUT -H "X-Tableau-Auth:GGxvSGb-SN6nzyLhfFuifQ|9sodYqlju7dZjjCyykh4fGn4kH7FJe3j" -d "@add-permissions.xml"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

The response body confirms that permissions were granted to the group.

<tsResponse xmlns="http://tableau.com/api"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-
	api-3.4.xsd">
		<permissions>
			<workbook id="0d110ecf-b4d8-42c0-af2b-756be5677eeb"
				name="new-workbook">
					<owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
			</workbook>
				<granteeCapabilities>
					<group id="6fdc89d1-2ee0-457a-a116-e028d9c35722"/>
					<capabilities>
						<capability name="Read" mode="Allow"/>
						<!— . . . other grantee capabilities . . . -->
					</capabilities>
				</granteeCapabilities>
	</permissions>
</tsResponse>

To verify that permissions were granted to the group, find your workbook on your server and view its permissions. To find these, choose the explore icon on the left, choose your workbook, and then choose the stacked dots menu next to the workbook name. In the menu, choose Permissions, and note that the new group you created is listed with the Read permissions you set.

Next Steps

Congratulations! You have completed the Tableau Server REST API Get Started tutorial. Now that you have some experience with the pattern of working with REST calls, you have the tools to explore the whole REST API surface of Tableau server. Some things you may want to try:


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