Get Started Tutorial Part 1: Tools, REST Basics, and Sign In

What is in part 1 of this tutorial?

This is part 1 of a 3-part tutorial to help you get started using the Tableau Server REST API. Setup steps and concepts you’ll need are described on the introduction page. We expect part 1 will take you about 20 minutes to complete.

Introduction and Set Up
Part 1: Tools, REST Basics, and Sign In (this page: ~20 minutes)
- Read about REST basics.
- Make a REST request to sign in to your server.
- Learn to use the server’s response to authenticate other requests.
Part 2: Create a Project and Publish a Workbook to It (~20 minutes)
Part 3: Create a User Group and Give it Permissions (~20 minutes)

Watch a video demonstration(Link opens in a new window) of signing in using the REST API through Postman.

The basics of REST

Already familiar with REST? Skip to Sign in to your server.

Why would I want to use the REST API to manage my Tableau Server and resources?

The Tableau Server REST API enables you to create a script or program that performs the same actions you can take through the server UI. That means you can automate repetitive tasks, create automated workflows that behave differently based on the condition of your Tableau resources, integrate Tableau management tasks into your existing workflows, and more.

How does REST work?

REST is a common pattern for making requests to and getting responses from an API (a server's or app's programming interface) over the web. Here are a few parts of the REST protocol you need to know about to get started.

Resource: The component of the API you want to query or manage, represented by a URI that contains the location of your server plus the resource you want. Typical Tableau Server resources are users, workbooks, and views. The URIs for resources are often referred to as endpoints and resemble URLs used for navigating to web pages.

The model of a URI to get the details of a Tableau workbook looks something like:
```
GET https://MY_SERVER/api/3.4/workbooks/workbook-id
```
Note that the server name and the workbook id are placeholders in the model. You would replace them to form a real example of a request.
Request: A message to a server describing the action you want to take relating to a resource.

Requests use an HTTP verb (action word found in typical web requests) to describe the action being requested. These include:
- GET (read information)
- POST (create new resources)
- PUT (update existing resources)
- DELETE (remove resources or configurations)
  Note that the model of a URI for a request tells you which verb to use.
Many requests have bodies that carry details of the request. For instance, a sign in request body carries a user's username and password credentials for the server to validate when authorizing the sign in.
Response: A server’s response to a request that contains information about the state of the resource after the request. Responses often have bodies that carry information resulting from the request. For instance, the response to a request for sign in has a body containing a credentials token that, in following requests, the server uses to validate that the user is already signed.
Response code: Tableau server also returns a response code that reports if the call was a success (200) or why it failed (400 or greater).
Header: All requests and responses have headers that contain information about them, for instance, the format (XML or JSON) of the response or request. They can also carry key information, such as when a request header contains the credentials token that allows a server to validate a user's sign in.

To learn more, see Fundamentals of the Tableau Server REST API.

For simplicity, we'll use username/password sign in for this tutorial. To log in to the server, you will call the signin method of the Tableau auth object.

URI

Start by constructing the URI for your request to sign in to your server. The model of the URI for a sign in request looks like:

POST https://MY_SERVER/api/api-version/auth/signin

Replace MY_SERVER with your Tableau server name, and api-version with the API version of your server (if you get the API version wrong, look for the right one in the error response from the server).

If you are using your Tableau Developer Program sandbox your URI might look like:

https://10ax.online.tableau.com/api/3.4/auth/signin

Request body

In the request body XML, add your login credentials. Replace the placeholders with valid user-name, password, and site-name.

Note: site-name refers to the name of your sandbox, if you are using your Developer Program sandbox. If you are signing in to Tableau Server use the site name. If you use the default site, leave the contentUrl value empty (contentUrl="").

<tsRequest>
	<credentials name="user-name" password="password">
		<site contentUrl="site-name" />
	</credentials>
</tsRequest>

If you just activated your Developer Program site and the URL is https://10ax.online.tableau.com/t/MarketingTeam your request body will look something like:

<tsRequest>
	<credentials name="jajohnson@example.com" password="mypassword">
		<site contentUrl="MarketingTeam" />
	</credentials>
</tsRequest>

Using Postman - To use Postman to make a sign in request:
1. Open Postman and select +New > Request.
2. In Request name, type "Sign in".
3. Choose +Create collection and name the new collection “REST Tutorial Collection".
4. Choose the check mark on the right of the form field, then choose Save to REST Tutorial Collection.
5. Change the verb on the upper left to POST, and then replace "Enter request URL " with your URI.
6. Select Body, then select raw.
7. Copy/Paste the body XML from the preceding section into the raw body area, ensuring the placeholders have been replaced with valid values.
8. Choose Send, then scroll down to view the response panel.
An animation of signing in with a Postman request. Click to replay.
Using cURL - To use cURL to make a sign in request:
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 signin.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 signin.xml. Replace MY_SERVER" with the name of your server in the following command, and then run it as follows.
```
cd /…/dir-containing-sign-in-xml
curl "https://MY-SERVER/api/3.4/auth/signin" -X POST -d "@signin.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 the response body looks like the following, then you have succeeded in signing in to your Tableau Server. You can confirm the sign in by viewing the users page of the server management.

<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">
		<credentials token="fDgkilutQqmJn0znEZr7Sg|0CHx3E9Sird1cOHv4yNVK86Y7opMmhKz">
			<site id="a946d998-2ead-4894-bb50-1054a91dcab3" contentUrl="mySite"/>
			<user id="cdfe8548-84c8-418e-9b33-2c0728b2398a"/>
		</credentials>
</tsResponse>

If you got an error, try to use the message in the response body to figure out if there is a password, server name or other problem. Otherwise, find the error response code in the response body and try looking at the sign in(Link opens in a new window) method error message list in the API reference.

Save your credentials token and site id

The response contains two pieces of information that you will need to complete the rest of the tasks in this tutorial:

The value of the credentials token: This token will allow the other calls to be authenticated as valid by your Tableau Server. To keep things secure, the token has a time limit, typically 2 hours. After that you'll need to sign in again and use the new token from the response for following requests.
The value of site id: This is the identifier for the site on your Tableau Server that you define in the contentUrl in your request body. Your users, workbooks and views are all children of your site object, and you need this identifier to make REST calls to them. If contentUrl is empty, then the default site’s id is returned.

Copy and save those two values for next steps in this tutorial.

Authentication of REST calls

Here's one more important piece of information about REST that you will use in all REST requests you make once you have signed in to a server.

Tableau Server responds to a sign in call with a credentials token. The token is used by the server to validate that a request comes from a signed-in user. When a token expires, typically after 2 hours, you will need to make a new sign in request to get a fresh token.

Every REST call to the server after sign in needs to pass a valid token to succeed. To pass the token you place it in the request header as a key/value pair:

key	Value (example)
`X-Tableau-Auth`	`fDgkilutQqmJn0znEZr7Sg\|0CHx3E9Sird1cOHv4yNVK86Y7opMmhKz`

Adding credentials to a request

Using Postman - To add credentials to a request header using Postman:
1. Open Postman and choose your request.
2. Select Headers.
3. In an empty row, in the Key column, type "X-Tableau-Auth".
4. In the Value column, enter the credentials token value you copied from response body of your sign in call.
An animation of adding credentials to a request header with Postman. Click to replay.
Using cURL - To add credentials to a request header using cURL

Add the key/value pair to your command using the Header parameter, abbreviated as -H.
```
curl "https://MY-SERVER/api/3.4/sites" -X POST -d "@signin.xml" -H "X-Tableau-Auth:fDgkilutQqmJn0znEZr7Sg|0CHx3E9Sird1cOHv4yNVK86Y7opMmhKz"
```

Next Up: Part 2: Create a Project and Publish a Workbook to It (~20 minutes)

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help