Authentication-Tableau Server REST API

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 Tableau Server or Tableau Cloud verify you as a valid, signed in user. To get a credentials token, you call Sign In and pass credentials of a valid user, either a Personal Access Token (PAT), a user name and password, along with the content URL (subpath) of the site you are signing in to. A subset of Tableau REST methods(Link opens in a new window) support authenticated sessions using a JSON Web Token (JWT), typically used in conjunction with a Tableau connected app(Link opens in a new window).

Notes:

The REST API does not support single-sign (SSO). To sign in, you must specify the name and password of a user who has been created on Tableau Server or Tableau Cloud. REST API calls will have the permissions of the user they sign in as. We strongly recommend PAT signin because it is more secure. For information about the requirements for using SAML, see SAML Requirements(Link opens in a new window) in Tableau Server Help and in Tableau Cloud Help.
(Tableau Cloud 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 Cloud.

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

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

Server path parameter

The my-server value in the sign in URI is the base URL for your Tableau Server. For Tableau Cloud, 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.24/auth/signin

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 (i.e., 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 example, 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 Cloud, see Personal Access Token(Link opens in a new window) in the Tableau Cloud Help.
For Tableau Server, see Personal Access Token(Link opens in a new window) in the Tableau Server Help.

When you create a Personal Access Token(Link opens in a new window), Tableau Cloud or Tableau Server displays a dialog that shows the PAT name and secret. There is no way to retrieve a secret after that Personal Access Token dialog is closed. Copy the secret value to use in your sign in request body.

Personal access token expiration

PATs expire if they are not used for 15 consecutive days. If they are used more frequently than every 15 days, the following can occur:

On Tableau Cloud, PATs expiration depends on the site setting, which is configurable by a site admin.
On Tableau Server, PATs expire after one year by default.

After PATs have expired they can’t be used for authentication and are removed from your My Account Settings page in Tableau Cloud or Tableau Server.

Request body

The XML request body (message payload) using a PAT 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"
		}
	}
}

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

A JSON Web Token (JWT) is an industry standard authorization method that allows an app to generate credentials for an authorized user. JWTs are commonly used in scenarios where authentication provided by one service enables authorization of another service. For instance, a user signs into an external app using their Google credentials, then the external app creates a JWT to authorize a user for Tableau credentials.

To authorize access to the REST API using a JWT, two things must be true. First, a Tableau connected app(Link opens in a new window) must be created by a Tableau Server administrator or Tableau Cloud site admin. Depending on the method used to create the connected app, a JWT can be generated by the connected app as part of the external app's call to sign in to Tableau. Second, the JWT also must contain JWT-supported access scopes(Link opens in a new window) that determine which methods the connected app can call.

Request body

The XML request body (message payload) for a sign in request using a JWT 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 jwt="eyJpc3MiOiI1NmUwZGZhYi0zNDA3LTRlNWMtYWY5Ni04YzI1ZmY0NWI3ODMiLCJhbGciOiJIUzI1NiIsImtpZCI6ImJlNzFkNDc0LWMxOTctNDljNS04ZWIzLTM5YWU4MWVjNDNhYyJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoidGVzdDEyMyIsInNjcCI6WyJ0YWJsZWF1OmNvbnRlbnQ6cmVhZCJdLCJpc3MiOiI1NmUwZGZhYi0zNDA3LTRlNWMtYWY5Ni04YzI1ZmY0NWI3ODMiLCJleHAiOjE2NDc2MjM1NzUsImp0aSI6ImY0MzdkNDFmLWM1MmMtNGE5Mi1hYTA1LWFjYTYyMGViZTgzMSJ9.pntsSpHmrxTT5XmiJi1Ls2qQdu4qMRQ5vgRuN7gtS_U" >
	<site contentUrl="MarketingTeam" />
  </credentials>
</tsRequest>

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

{
  "credentials": {
    "jwt": "eyJpc3MiOiI1NmUwZGZhYi0zNDA3LTRlNWMtYWY5Ni04YzI1ZmY0NWI3ODMiLCJhbGciOiJIUzI1NiIsImtpZCI6ImJlNzFkNDc0LWMxOTctNDljNS04ZWIzLTM5YWU4MWVjNDNhYyJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoidGVzdDEyMyIsInNjcCI6WyJ0YWJsZWF1OmNvbnRlbnQ6cmVhZCJdLCJpc3MiOiI1NmUwZGZhYi0zNDA3LTRlNWMtYWY5Ni04YzI1ZmY0NWI3ODMiLCJleHAiOjE2NDc2MjM1NzUsImp0aSI6ImY0MzdkNDFmLWM1MmMtNGE5Mi1hYTA1LWFjYTYyMGViZTgzMSJ9.pntsSpHmrxTT5XmiJi1Ls2qQdu4qMRQ5vgRuN7gtS_U",
    "site": {
    "contentUrl": "MarketingTeam"
    }
  }
}

About 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 Cloud 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 Cloud - https://10ay.online.tableau.com/#/site/MarketingTeam/workbooks

Notes:

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 Cloud, 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 credentials 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="HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3">
    <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": "HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"
    }
}

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 Credentials Token In Subsequent Calls

When you get the response, you parse the credentials token out of the response and store it in your application. By default, the credentials 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 credentials token has expired, you can call Sign In again and get a new credentials token.

You include the credentials token as the value of the X-Tableau-Auth header for all other REST API calls.

For example:

X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3

Note: The credentials token is valid for REST API calls and Tableau Metadata API (GraphQL) queries. You cannot use the credentials token as authentication for other operations with Tableau Server or Tableau Cloud. In addition, the credentials 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 credentials token, which makes sure that no one else can use the credentials token to make calls to the REST API.

Impersonating a User

If you are a system administrator on Tableau Server, 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:

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 credentials 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 Cloud 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 credentials 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 credentials 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 credentials 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!')

Python Example for Sign In and Sign Out (JSON)

The following example in Python shows how to use the REST API to sign in to Tableau Server and get back an credentials token. The example supports JSON request and response payloads. Support for JSON was introduced in REST API 2.5. 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 Requests library. Use HTTPS requests when working with Tableau Cloud or a Tableau Server that is configured to use SSL.
The code creates and parses the JSON block in the response body using the Requests and JSON libraries. For details, see the 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 a credentials token and
# site ID, and then sign out.
# The example runs in Python 2.7 and Python 3.3 code

import requests, json


# 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:
	#
	# {
	# 	 "credentials": {
	#		 "personalAccessTokenName": "TOKEN_NAME",
	#		 "personalAccessTokenSecret": "TOKEN_VALUE",
	#	     "site": {
	#		   "contentUrl": ""
	#	     }
	#     }
	# }
	#

	payload = { "credentials": { "personalAccessTokenName": personal_access_token_name, "personalAccessTokenSecret": personal_access_token_secret, "site": {"contentUrl": site_url_id }}}

	headers = {
		'accept': 'application/json',
		'content-type': 'application/json'
	}

else:
	# The following code constructs the body for the request. The resulting element will# look similar to the following example:
	#
	#
	# {
	# 	 "credentials": {
	#		 "name": "USERNAME",
	#		 "password": "PASSWORD",
	#	     "site": {
	#		   "contentUrl": ""
	#	     }
	#     }
	# }
	#

	payload = { "credentials": { "name": user_name, "password": password, "site": {"contentUrl": site_url_id }}}

	headers = {
		'accept': 'application/json',
		'content-type': 'application/json'
	}

# Send the request to the server
req = requests.post(signin_url, json=payload, headers=headers, verify=False)
req.raise_for_status()

# Get the response
response = json.loads(req.content)

# Parse the response JSON. The response body will look similar
# to the following example:
#
# {
#	 "credentials": {
#		 "site": {
#			 "id": "xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxx",
#			 "contentUrl": ""
#		 },
#		 "user": {
#			 "id": "xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxx"
#		 },
#		  "token": "CREDENTIALS_TOKEN"
#	 }
# }
#

# Get the credentials token from the credentials element
token = response["credentials"]["token"]

# Get the site ID from the <site> element
site_id = response["credentials"]["site"]["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 = requests.post(signout_url, data=b'', headers=headers, verify=False)
req.raise_for_status()
print('Sign out successful!')

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help

Signing In and Signing Out (Authentication)

Sign In URI

Make a Sign In Request with a Personal Access Token

Personal access token expiration

Request body

Make a Sign In Request with Username and Password

Make a Sign In Request with a JWT

Request body

About the Site Attribute

Response for a Successful Sign In Operation

Using the Credentials Token In Subsequent Calls

Impersonating a User

Python Example for Sign In and Sign Out (XML)

Python Example for Sign In and Sign Out (JSON)