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.

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

The Sign In URI

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

POST http://my-server/api/3.6/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.6/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 info 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 Personal Access Token.

When you create a Personal Access Token, 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 : text/xml, or Content : 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 : 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 : text/xml, or Content : 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 : 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, if a sign in request body is missing a site element, is missing the contentUrl attribute, or contains a contentUrl whose value is an empty string, then the result is identical to specifying the Default site as the contentUrl.

For Tableau Online, a site element containing a contentUrl with the value of an existing site must always be provided. 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:

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 versions](#rest_api_concepts_versions.htm).

  • 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 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!')

 

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 authentication 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 versions](#rest_api_concepts_versions.htm).

  • 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 Online 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 an authentication 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 authentication 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! There was an error submitting your feedback. Try again or send us a message.