The basics of REST

REST refers to a set of attributes of a particular architectural style, while HTTP is a well-
defined communication protocol.

Tableau has its own application programming interface that allow the communication with
the set of attributes of its particular architectural style (which includes the way the organize
their data and their business rules for that data) (REST) and REST refers to a set of
attributes of a particular architectural style. REST is based on HTTP communication
protocol, this is why REST contains the same verbs (get, post, put,...

delete).

Few parts of the REST protocol

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.

URI example to get details of a Tableau Workbook

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)

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.

REST refers to a set of attributes of a particular

architectural style, while HTTP is a well-defined

communication protocol.

Tableau has its own application programming interface

that allow the communication with the set of attributes

of its particular architectural style (which includes

the way the organize their data and their business rules

for that data) (REST) and REST refers to a set of

attributes of a particular architectural style. REST

is based on HTTP communication protocol, this is

why REST contains the same verbs (get, post, put,...

delete).

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:

o GET (read information)

o POST (create new resources)

o PUT (update existing resources)

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

Step 1: Sign in to your server with REST

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

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>

Make a REST sign in request

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

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:

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

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

Here are the requirements for using the Tableau Server REST API:

 Tableau Server version: To program with the REST API, you need Tableau Server
9.0 or a later version. Some methods were added in later versions of Tableau Server.
The documentation for individual API methods indicates the version of Tableau
Server that's required for using that method.

 API enabled: By default, Tableau Server is installed with the REST API enabled,
but it can be disabled. To disable or enable the REST API, use the tsm configuration
set(Link opens in a new window) command. Change the api.server.enabled(Link
opens in a new window) setting to true to enable the API or false to disable the
API.
Fundamentals of the Tableau Server
REST API
Tableau Server provides an application programming interface (API) that lets you
programmatically manage users, workbooks, data connections, and other resources on the
server. By using the API, you can create users or import them from Active Directory,
publish workbooks, create, view, and delete data sources, and perform other actions on the
server.

Using the API, you can perform many of the tasks that you can do using tabcmd. However,
the REST API methods provide more granular control over your interaction with the server.
You can think of them as a set of programmatic blocks that you can use to put together
complex operations that chain the output of one operation to the input of the next one, and
that might involve conditions and other scenarios that are best addressed in programming
logic.

About the REST API

The Tableau Server REST API is based on the principles of REST (representational state
transfer) protocol for client-server communication. In Tableau Server, the client-server
communication occurs over HTTP, using standard web requests.

In REST, resources are identified in a consistent way using a URI (uniform resource
identifier). Actions are expressed using standard verbs like GET and POST. The client
passes all necessary information to the server for each action—that is, the server does not
have to maintain any state about the client. For more information about REST principles
and architecture, see A Brief Introduction to REST(Link opens in a new window).
Note: As a security measure, you should make API calls to Tableau Server using the
HTTPS protocol (SSL/TLS). See Using HTTPS (SSL/TLS) for API Calls.

Using HTTP Verbs to Request Server Actions

When you work with the Tableau Server REST API, you use the following HTTP verbs to
request actions from the server:

 GET to read information, such as getting a list of users or downloading a workbook.

 POST to create or publish new resources, such as sites, users, workbooks, and data
sources.

 PUT to update existing resources, such as updating a user’s password, updating

permissions, or changing a workbook owner.

 DELETE to remove a resource, such as deleting a user, or workbook. This verb can
also dissociate a resource from a collection—for example, you can use the DELETE
verb to remove a user from a site, which dissociates the user from collection of
users on the site, but doesn't remove the user from the server.
Using URIs to Specify Resources
The HTTP verb indicates the type of operation you want to perform on a resource. You
indicate what resource to work with by making requests using a URI. The URI specifies the
site, project, workbook, user, or other resource that you are creating, viewing, or deleting.
For example, to get a list of the users in a specific group, you send a GET request that has
the following format:

https://your-server/api/3.15/sites/site-id/groups/group-id/users

In this URI, your-server is the name or IP address for your Tableau Server installation.
The site-id value is an identifier for the site, and group-id is an ID for the group.

In the previous example, you used a GET request because you were reading resources from
the server. To delete a workbook, you would send a DELETE request that has this form:

https://your-server/api/3.15/sites/site-id/workbooks/workbook-id

As in the previous example, you substitute your own values for your-server and site-id. In

this case, for workbook-id, you would include the unique identifier for the workbook you
want to delete.

The URI specifies a hierarchy for the resource. To get users in a group, you use a URI that
includes sites and the site ID, and then groups and the group within that site, and
finally users to indicate that you want users from the specified group. In the URI for
deleting a workbook, you specify sites plus the site ID, then workbooks plus the ID of the
workbook to delete.

You reference other resources in a similar way. The following URI specifies an individual
project on the site:

https://your-server/api/3.15/sites/site-id/projects/project-id

This example URI specifies an individual data source on the site:

http://your-server/api/3.15/sites/site-id/datasources/datasource-id
And this URI references the preview image for an individual view within a specific
workbook on the site:

https://your-server/api/3.15/sites/site-id/workbooks/workbook-id/views/view-id/previewImage

Notice in these examples that the URI itself does not contain information about the
operation to perform—for example, when you want to delete a workbook, there’s nothing
in the URI that includes a term like “delete” or “remove.” The action is specified only by
the HTTP verb that you use when you make the request (DELETE); the URI indicates only
the resource on which the action should take place.

Sending Information for New and Updated Resources

(POST and PUT)
You create new resources by sending a POST request, and you update existing ones by
sending a PUT request. You include the information for the operation in the body of the
request, sometimes referred to as the payload or simply the data.

Note: For POST and PUT requests, the request should include the Content-Length and Content-

Type headers. The request can be in XML or JSON. For more information, see Passing
MIME Type and Authentication Information in the Header.

For example, to create a user on a site, you send a POST request using a URI in the
following format:

https://your-server/api/3.15/sites/site-id/users/

The information for the new user can be placed in the body of the request block. The
request block can be in either XML or JSON. By default, the Content-Type is (text/xml). If you
use XML, the block must have root element called <tsRequest>. The body of the
XML request might look like the following:

<tsRequest>
<user name="Bob"
siteRole="Viewer" />
</tsRequest>

If you set the Content-Type to JSON (application/json), the request block might look like the
following:

{
"user": {
"name": "Bob",
"siteRole": "Viewer"
}
}

The siteRole value is the role you want the new user to have, such as Viewer, Publisher,
or Interactor. In response to the POST request to create a user, Tableau Server returns the
response that includes the user-id assigned to the new user.

To update a user, you make a PUT request and use a URI like the following to update the
user with the specific user-id:

http://your-server/api/3.15/sites/site-id/users/user-id
In XML, the body of the request might look like this:

<tsRequest>
<user fullName="Adam Davis"
email="[email protected]"
password="passw0rd" />
</tsRequest>

Or like the following in JSON:

{
"user": {
"fullName": "Adam Davis",
"email": "[email protected]",
"password": "passw0rd"
}
}

Note: Some query path parameters, such as user-id in the preceeding example, are legal in
both the query and request body parameters of a REST API method. Where this is true, the
parameter should be declared in the query path, not the request body. If it is declared in
both places, the request body parameter value will be ignored.

The XML and JSON requests and responses follow a schema. You can use the XML
schema to generate classes that you can use when programming. For more information,
see REST API XML Schema.

Passing MIME Type and Authentication Information in

the Header
Some information for a request is passed using the request header. This includes the content
length, MIME-type information, and authentication information.

 All POST and PUT requests should include the Content-Length header, which

indicates the length of the request body.

 All POST and PUT requests should include a Content-Type header that indicates the

MIME type of the data in the request body. For most POST and PUT requests, this
should be text/xml or application/xml for XML and application/json for JSON. If not
 specified, the default is text/xml. If the Accept header is specified, it must match
the Content-Type; use application/json or application/xml. (Setting the Content-Type heading
to an incorrect type, such as application/x-www-form-urlencoded, can result in
unexpected corruption of your posted data.)

For publish requests like Publish Datasource and Publish Workbook, the Content-

Type header is set to multipart/mixed; boundary=boundary-string, where boundary-string is
a string that is used to separate parts of the request body. For more information,
see Publishing Resources.

 To specify whether you want the response in XML or JSON, set the Accept header.
By default, the response matches the Content-Type. If the Accept header and Content-
Type are not specified, the default is text/xml and application/xml.

 All requests except the initial Sign In request must include an authentication token

in the X-Tableau-Auth header. For more information about signing in and
authentication, see Signing In and Signing Out (Authentication).

Enabling CORS on Tableau Server for the REST API

For security, most web browsers restrict HTTP requests to the same origin. That is, to
access a resource on a server through an API, the request must come from the same origin
(server), or a proxy must be set up to handle the request.

Tableau Server now supports Cross-Origin Resource Sharing (CORS), so you can do away

with your proxy and call the REST API from the browser. The CORS mechanism is
currently only enabled for Tableau Server, and can be turned on by server administrators in
a couple of steps using the TSM command-line tool. To learn more, see the description of
the vizportal.rest_api.cors.allow_origin option in tsm configuration set Options. As a security
measure, you should make API calls to Tableau Server using the HTTPS protocol (SSL or
TLS). See Using HTTPS (SSL/TLS) for API Calls.

1. Add the origins that need access to the Tableau Server.

Determine the origins (servers) you want to allow access to the REST API, and use
the tsm configuration set command with the vizportal.rest_api.cors.allow_origin option. For
example, to grant access to one two origins, https://mysite and https://yoursite, you
would stop the server (tsm stop) and then use the following command:

tsm configuration set -k vizportal.rest_api.cors.allow_origin -v https://mysite,https://yoursite

 You can enter multiple origins. Use a comma to separate the entries.

Note: You could also use an asterisk (*) as a wild card to match all sites. This is not
recommended as it allows access from any origin that has access to the server and
could present a security risk. Do not use an asterisk (*) unless you fully understand
the implications and risks for your site.

2. Enable CORS on Tableau Server.

Use the tsm configuration set command with the vizportal.rest_api.cors.enabled option. The

default setting is false, so set this to true as follows:

tsm configuration set -k vizportal.rest_api.cors.enabled -v true

3. Update your Tableau Server configuration (tsm pending-changes apply)  to restart

Tableau Server and make the changes take effect.  Only the origins you specify will
have access.

For information about CORS, see https://www.w3.org/TR/cors/

Passing Additional Information in the Query String
For some calls, you pass parameters using the query string. These parameters indicate
processing instructions for the request, as distinct from data. One example is
the overwrite query string parameter that you can include when you publish a workbook,
to indicate that Tableau should overwrite any existing workbook. Another example is
pagination instructions. The following example shows the URI for a GET request to list all
the sites on the server. The parameters in the query string specify that the request should
return elements 51 through 100.

https://my-server/api/3.15/sites?pageSize=50&pageNumber=2

Some methods also let you pass parameters in the query string that let you filter the results
to return. For example, when you call Get Users on Site, you can add the filter parameter
and a filter expression like the following to the URI in order to return only users whose site
role is Viewer:

https://MY-SERVER/api/3.15/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Viewer

For some methods, you can also add the sort parameter and a sort expression to the query
string, as in this example:

https://MY-SERVER/api/3.15/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?sort=name:desc

For some methods, you can add the fieldsparameter to qualify the results by the fields and
resources you are interested in. For example, when you call List Metrics for Site, you can
add the fields parameter and a field expression to return just the id and name of all the
workbooks: 

https://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/workbooks?fields=id,name

 
For more information, see Filtering and Sorting in the Tableau REST API and Using Fields
in the REST API.

Getting Results from the Server

Tableau Server sends a response to each REST API request. The response includes a
standard HTTP status code, such as 200 (OK) or 201 (Created). For most requests, the
server returns a response body as you specify in the Acceptor Content-Type header as either
JSON or XML. In XML, the root element is <tsResponse>.

(The exception is DELETE requests. These do not return a response body. The HTTP status
code for successful DELETE operations is 204 (No Content), because there is nothing to
return.)

For example, to get a list of projects for a site, you make a GET request using a URI with
the following format:

https://your-server/api/3.15/sites/site-id/projects

The body of the response includes the list of projects. It might look like the following
XML example:

<?xml version="1.0" encoding="UTF-8"?>

<tsResponse version-and-namespace-settings >
<pagination pageNumber="1" pageSize="100"
totalAvailable="16" />
<projects>
<project id="project-id" name="SampleProject"
description="This is a test project" />
<project id="project-id" name="MarketingProject"
description="Contains resources used by the Marketing department" />
... more projects ...
</projects>
</tsResponse>
The response body is an XML block. The <tsResponse> element includes attributes that
specify the XML namespace for the elements, and the location of the XML schema that
defines the structure for the XML block. (For an introduction to XML namespaces,
see Understanding XML Namespaces(Link opens in a new window) in MSDN Magazine.)

Following these declarations, the <projects> element contains a collection

of <project> elements. Each one includes information about an individual project.
This response also includes a <pagination> element that is useful if the number of projects
is large and you need to make multiple requests to get successive pages of project
information. For more information about paginating results, see Paginating Results.

When you create or update a resource, the body of the response lists the new or updated
state of the affected resource. For example, to create a new project, you make a POST
request using a URI with the following format:

https://your-server/api/3.15/sites/site-id/projects

The body of the request contains the XML that defines the new project values.

In XML:

<tsRequest>
<project name="SampleProject"
description="This is a new description of the test project" />
</tsRequest>

In JSON:

{
"project": {
"name": "SampleProject",
"description": "This is a new description of a test project"
}
}

If the request is successful, the response body includes a block that describes the new
project.

In XML:

<?xml version="1.0" encoding="UTF-8"?>

<tsResponse version-and-namespace-settings >
<project id="1f2f3e4e5-d6d7-c8c9-b0b1-a2a3f4f5e6e"
name="SampleProject"
description="This is a new description of the test project" />
</tsResponse>

In JSON:
{
"project": {
"id": "1f2f3e4e5-d6d7-c8c9-b0b1-a2a3f4f5e6e",
"name": "SampleProject",
"description": "This is a new description of a test project",
"contentPermissions": "ManagedByOwner"
}
}

Notice that the response body echoes some of the information that you sent in the request
body. The server is returning state information about the project to the client, including
both the information you originally sent (name and description) and new information (the
ID that was generated for the new project). Having the original request information echoed
in the response makes it easier to use that information as input into a subsequent request
(that is, to chain requests), because you don’t have to save this information in your
application between calls.

Signing In and Signing Out

(Authentication)
The Tableau Server REST API requires that you send a credentials token with each request.
The credentials token lets the server verify you as a valid, signed in user. To get a token,
you call Sign In and pass credentials of a valid user, either a Personal Access Token (PAT)
or a user name and password, along with the content URL (subpath) of the site you are
signing in to.

Notes:

 SAML single sign on (SSO) authentication does not validate REST API requests.
Even if you are manually signed in to your server through SSO, REST API request
authentication requires that you first make a REST sign in request, and then use the
credentials token from its response in the header of subsequent requests. For
information about the requirements for using SAML, see SAML Requirements.
(Link opens in a new window)

 (Tableau Online only) If multi-factor authentication (MFA) is enabled with Tableau

authentication, PATs are required. You must use a PAT, instead of user name and
password, to make a REST API sign in request to Tableau Online.

The Sign In URI

The following example shows the URI for a Sign In using a POST request:

POST http://my-server/api/3.15/auth/signin

Server path parameter

The my-server value in the sign in URI is the base URL for your Tableau Server. For
Tableau Online, the server address in the URI must contain the pod name, such
as 10az, 10ay, or us-east-1. For example, the URI to sign in to a site in the 10ay pod would be:

https://10ay.online.tableau.com/api/3.15/auth/signin

Make a Sign In Request with a Personal Access Token

A Personal Access Token (PAT) validates that a user is allowed to sign in to a site. A sign
in using a PAT returns the same information as a username and password sign in (a
credentials token, site LUID, and user LUID), but without the security risk of exposing
hard-coded usernames and passwords, or an interactive login experience. PATs are long-
lived, and can be revoked without disabling the Tableau user they are attached to. A user
can have multiple PATs, which allows for granular monitoring and revocation of access
rights. For instance, an admin might group their scripts into functional areas (like
permissions, subscriptions, and data source refreshes) and use a different PAT for each
area. For more information, see one of the following topics: 

 For Tableau Server, Personal Access Token(Link opens in a new window).

 For Tableau Online, Personal Access Token(Link opens in a new window).

When you create a Personal Access Token(Link opens in a new window), Tableau displays
a dialog that shows the token name and token secret. There is no way to retrieve a token
secret from the server after that dialog is dismissed. Copy those values to use in your sign
in request body

Personal Access Tokens will expire if they are not utilized for 15 consecutive days. If they
are regularly used more frequently than every 15 days, an access token will expire after 1
year, and need to be replaced with a newly created one.

The XML request body (message payload) using a Personal Access Token looks like the
following example. The header of the request should contain either the key value
pair Content-Type : text/xml, or Content-Type : application/xml.

<tsRequest>
<credentials
personalAccessTokenName="MY_TOKEN_NAME"
personalAccessTokenSecret="qlE1g9MMh9vbrjjg==:rZTHhPpP2tUW1kfn4tjg8" >
<site contentUrl="MarketingTeam" />
</credentials>
</tsRequest>

The same request body using JSON looks like the following. Its header should
contain Content-Type : application/json.
{
"credentials": {
"personalAccessTokenName": "MY_TOKEN_NAME",
"personalAccessTokenSecret": "qlE1g9MMh9vbrjjg==:rZTHhPpP2tUW1kfn4tjg8",
"site": {
"contentUrl": "MarketingTeam"
}
}
}

Make a Sign In Request with Username and Password

The XML request body (message payload) for a sign in request using a username and
password looks like the following example. The header of the request should contain either
the key value pair Content-Type : text/xml, or Content-Type : application/xml.

<tsRequest>
<credentials name="admin" password="p@ssword" >
<site contentUrl="MarketingTeam" />
</credentials>
</tsRequest>

The same request body using JSON looks like the following. Its header should
contain Content-Type : application/json.

{
"credentials": {
"name": "admin",
"password": "p@ssword",
"site": {
"contentUrl": "MarketingTeam"
}
}
}
The Site Attribute
The site element of a sign in request lets you specify the site to sign in to by setting the
value of the contentUrl attribute. The content URL is the subpath of a site's full URL. In the
server environment, it is referred to as the Site ID. When you sign in to Tableau Server or
Tableau Online manually, the contentUrl is the the value that appears after /site/ in the
Browser address bar. For example, in the following URLs, the content URL
is MarketingTeam:

(Tableau Server) http://MyServer/#/site/MarketingTeam/projects

(Tableau Online) https://10ay.online.tableau.com/#/site/MarketingTeam/workbooks

For Tableau Server, to specify the default site, omit contentUrl from the site element, or make
the contentUrl value an empty string (contentUrl="").

For Tableau Online,a sign in request must have a site element containing a contentUrl with
the value of an existing site. If these are missing, the Sign In request will fail.
Response for a Successful Sign In Operation
If the Sign In call is successful, the body of the response contains an authentication token,
the site ID of the site you're signed in to, and the user ID of the user you're signed in as. The
following example shows the response in XML (when Content-Type header is set
to text/xml or application/xml or when the Accept header is set to application/xml).

<?xml version="1.0" encoding="UTF-8"?>

<tsResponse version-and-namespace-settings>
<credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
<site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</credentials>
</tsResponse>

In JSON, the response would look like the following (when Content-Type or

the Accept header is set to application/json),

{
"credentials": {
"site": {
"id": "9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d",
"contentUrl": ""
},
"user": {
"id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
},
"token": "12ab34cd56ef78ab90cd12ef34ab56cd"
}
}
The id attribute is the LUID, or locally unique identifier, for the site. In the preceding
example, the site LUID is 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d. Many REST API methods
require the site LUID to specify the site in their URI. For more information, see Identifying
Resources Using Locally Unique Identifiers (LUIDs).

Using the Authentication Token In Subsequent Calls

When you get the response, you parse the token out of the response and store it in your
application. By default, the token is good for 240 minutes. (You can specify a different
timeout value for the token by calling the tsm configuration set command to change
the wgserver.session.idle_limit setting.) If your application needs to be able to make
additional calls after the token has expired, you can call Sign In again and get a new
authentication token.

You include the authentication token as the value of the X-Tableau-Auth header for all
other REST API calls. For example:

X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd

Note: The token is valid for REST API calls and Tableau Metadata API (GraphQL)
queries. You cannot use the token as authentication for other operations with Tableau
Server. In addition, the token is good only for operations in the site that you're signed in to.
You cannot sign in to one site and then use the token you get back to send requests to a
different site. If you do, the server returns an HTTP 403 (Forbidden) error.

When you are finished with a session, you call Sign Out. This invalidates the token, which
makes sure that no one else can use the authentication token to make calls to the REST
API.
Impersonating a User
If you are a system administrator, you can sign in using your username and password
credentials for that role, and then impersonate any user on the system. This might be useful
if sign-in is being managed by a process that runs as a specific user (the administrator) but
needs to be able to access Tableau Server using different user identities.

While you are signed in impersonating a user, you will have that user’s permissions. If the
user is not an administrator, their permissions will limit your ability to make some REST
calls.

To sign in using impersonation, you include a user element in the request body and specify
the Tableau Server user ID (not name) of the user to impersonate, as in the following XML
request:

<tsRequest>
<credentials name="admin" password="p@ssword" >
<site contentUrl="Marketing" />
<user id="9f9e9d9c8-b8a8-f8e7-d7c7-b7a6f6d6e6d" />
</credentials>
</tsRequest>

Or in JSON:

{
"credentials": {
"name": "admin",
"password": "p@ssword",
"site": {
"contentUrl": "Marketing"
},
"user": {
"id": "9f9e9d9c8-b8a8-f8e7-d7c7-b7a6f6d6e6d"
}
}
}

You can get a user ID by using one of the following methods:

 Add User to Site

  Get Users on Site

 Get Users in Group

Python Example for Sign In and Sign Out (XML)

The following example in Python shows how to use the REST API to sign in to Tableau
Server and get back an authentication token. Note the following about this example:

 The code illustrates a Sign In request and a Sign Out request.

 By default, your sign in will use a personal access token for authentication
credentials. You must set the use-pat-flag to False to use username and password as
credentials.

 You must substitute the name of your own server for the MY-SERVER placeholder.

 You must substitute the API version number of your own server for
the version placeholder. To find your server's API version number, see REST API
and Resource Versions.

 You must substitute your own credential values in either

the TOKEN_NAME and TOKEN_SECRET, or USERNAME and PASSWORD placeholders.

 The code makes HTTP requests using the urllib2 library that is built into Python.
Use HTTPS requests when working with Tableau Online or a Tableau Server that is
configured to use SSL.

 The code creates and parses the XML block in the response body using the built-
in ElementTree method. For details, see the ElementTree XML API(Link opens in a
new window) documentation on the Python website.

For additional examples, see REST API Samples.

# This example shows how to use the Tableau Server REST API
# to sign in to a server, get back an authentication token and
# site ID, and then sign out.

# The example runs in Python 2.7 and Python 3.3

try:
# Python 3
from urllib.request import urlopen, Request
except ImportError:
# Python 2
from urllib2 import urlopen, Request
import xml.etree.ElementTree as ET # For parsing XML responses

# NOTE! Substitute your own values for the following variables:

use_pat_flag = True # True = use personal access token for sign in, False = use username and password
for sign in.

server_name = "YOUR_SERVER" # Name or IP address of your installation of Tableau Server

version = "x.x" # API version of your server
site_url_id = "SITE_SUBPATH" # Site (subpath) to sign in to. An empty string is used to specify the
default site.

# For username and password sign in

user_name = "USERNAME" # User name to sign in as (e.g. admin)
password = "PASSWORD"

# For Personal Access Token sign in

personal_access_token_name = "TOKEN_NAME" # Name of the personal access token.
personal_access_token_secret = "TOKEN_VALUE" # Value of the token.

signin_url = "https://{server}/api/{version}/auth/signin".format(server=server_name, version=version)

if use_pat_flag:
# The following code constructs the body for the request. The resulting element will
# look similar to the following example:
#
#
# <tsRequest>
# <credentials personalAccessTokenName="TOKEN_NAME"
# personalAccessTokenSecret="TOKEN_VALUE" >
# <site contentUrl="SITE_SUBPATH" />
# </credentials>
# </tsRequest>
#

request_xml = ET.Element('tsRequest')
credentials = ET.SubElement(request_xml, 'credentials',
personalAccessTokenName=personal_access_token_name,
personalAccessTokenSecret=personal_access_token_secret)
site_element = ET.SubElement(credentials, 'site', contentUrl="")

else:
# The following code constructs the body for the request. The resulting element will
# look similar to the following example:
#
#
# <tsRequest>
# <credentials name="USERNAME" password="PASSWORD" >
# <site contentUrl="SITE_SUBPATH" />
# </credentials>
 # </tsRequest>
#

request_xml = ET.Element('tsRequest')
credentials = ET.SubElement(request_xml, 'credentials',
name=user_name, password=password)
site_element = ET.SubElement(credentials, 'site', contentUrl="")

request_data = ET.tostring(request_xml)

# Send the request to the server

req = Request(signin_url, data=request_data, method="POST")
req = urlopen(req)

# Get the response

server_response = req.read()

# Parse the response XML. The response body will look similar
# to the following example:
#
#
# <tsResponse>
# <credentials token="CREDENTIALS-TOKEN" >
# <site id="xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxx" contentUrl="SITE-SUBPATH" />
# </credentials>
# </tsResponse>
#

response_xml = ET.fromstring(server_response)

# Get the authentication token from the <credentials> element

token = response_xml.find('.//t:credentials',
namespaces={'t': "http://tableau.com/api"}).attrib['token']

# Get the site ID from the <site> element

site_id = response_xml.find('.//t:site',
namespaces={'t': "http://tableau.com/api"}).attrib['id']

print('Sign in successful!')
print('\tToken: {token}'.format(token=token))
print('\tSite ID: {site_id}'.format(site_id=site_id))

# Set the authentication header using the token returned by the Sign In method.
headers = {'X-tableau-auth': token}

# ... Make other calls here ...

# Sign out
signout_url = "https://{server}/api/{version}/auth/signout".format(server=server_name,
version=version)
req = Request(signout_url, headers=headers, data=b'')
req = urlopen(req)
print('Sign out successful!')
*** ver ejemplo para jason y Python en la ayuda en esta sección.

Using HTTPS (SSL/TLS) for API Calls

As a security measure, you should make API calls to Tableau Server using the HTTPS
protocol (SSL or TLS)—that is, using an encrypted channel between your client and
Tableau Server. Information is passed as plaintext between the client and server using XML
or JSON blocks in the request and response body. Using HTTPS protocol helps keep this
information secure.

To make API calls with HTTPS, you must configure Tableau Server to use SSL. For
details, see SSL(Link opens in a new window) in the Tableau Server documentation. (If
you are testing Tableau Server, you can install a self-signed certificate in order to support
SSL.) If you make an HTTPS call to Tableau Server but you have not configured the server
to use SSL, the server refuses the request.

When working with Tableau Online, you must use the HTTPS protocol to make API calls.