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 callSign 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. Asubset 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 Tableauconnected app(Link opens in a new window).

Sign In URI

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

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

Server path parameter

Themy-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 as10az,10ay, orus-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.27/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 (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, seePersonal Access Token(Link opens in a new window) in the Tableau Cloud Help.
• For Tableau Server, seePersonal Access Token(Link opens in a new window) in the Tableau Server Help.

When youcreate 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 yourMy 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 pairContent-Type :text/xml, orContent-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 containContent-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 pairContent-Type :text/xml, orContent-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 containContent-Type :application/json.

{  "credentials": {    "name": "admin",    "password": "p@ssword",    "site": {      "contentUrl": "MarketingTeam"    }  }}

Make a Sign In request with a JWT

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

JWTs are enabled through Tableau connected apps or unified access tokens (Tableau Cloud only).

For more information about connected apps, see one of the following:

• Tableau Cloud -Use Tableau Connected Apps for Application Integration(Link opens in a new window)

• Tableau Sever -Use Tableau Connected Apps for Application Integration(Link opens in a new window)

For more information about UATs, seeUnified Access Tokens(Link opens in a new window) in the Tableau Cloud Manager REST API Help.

Access scopes

To ensure minimum access to administrative tasks and content, the JWT should contain access scopes that determine which methods are accessible to the connected app or UAT.

Both connected apps and UATs share the same access scopes.

You can find the required scope for a JWT-supported method in its properties block or section in the Tableau REST API Help or TCM REST API Help. If a scope is not listed in the method, access to that method can’t be controlled by a JWT.

For more information about access scopes for connected apps, see one of the following:

• Tableau Cloud -Access scopes for connected apps(Link opens in a new window)

• Tableau Server -Access scopes for connected apps(Link opens in a new window)

For more information about UAT scopes, seeAbout least privileged and access scopes(Link opens in a new window).

Sign in with connected apps JWT

One method you can use to to authorize access to the REST API using a JWT is using Tableau connected apps. For a connected apps workflow, two things must be true. First, a Tableauconnected app(Link opens in a new window) must be created by a Tableau Server administrator or Tableau Cloud site admin. Depending on the type of 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-supportedaccess 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 pairContent-Type :text/xml, orContent-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 containContent-Type :application/json.

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

Sign in with unified access token JWT

(Tableau Cloud only)

Another method to authorize access to the REST API using a JWT is through unified access tokens (UAT). UATs are configurations that must be generated through theTableau Cloud Manager REST API(Link opens in a new window) and be associated with the JWT token that is used to sign in to the Tableau REST API. To ensure minimum access to administrative tasks and content, the JWT should contain access scopes that determine which methods are accessible to the UAT.

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 pairContent-Type : text/xml, orContent-Type : application/xml.

<tsRequest>  <credentials jwt="eyJpc3MiOiI1NmUwZGZhYi0zNDA3LTRlNWMtYWY5Ni04YzI1ZmY0NWI3ODMiLCJhbGciOiJIUzI1NiIsImtpZCI6ImJlNzFkNDc0LWMxOTctNDljNS04ZWIzLTM5YWU4MWVjNDNhYyJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoidGVzdDEyMyIsInNjcCI6WyJ0YWJsZWF1OmNvbnRlbnQ6cmVhZCJdLCJpc3MiOiI1NmUwZGZhYi0zNDA3LTRlNWMtYWY5Ni04YzI1ZmY0NWI3ODMiLCJleHAiOjE2NDc2MjM1NzUsImp0aSI6ImY0MzdkNDFmLWM1MmMtNGE5Mi1hYTA1LWFjYTYyMGViZTgzMSJ9.pntsSpHmrxTT5XmiJi1Ls2qQdu4qMRQ5vgRuN7gtS_U" >   isUat= "true"   <site contentUrl="MarketingTeam" />  </credentials></tsRequest>

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

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

About the pod name

(Tableau Cloud only)

The server address in the URI must contain the pod name, such as "prod-ca-a". For example, the URI to sign in to a site on the "prod-ca-a" pod would be:https://prod-ca-a.online.tableau.com/api/api-version/auth/signin

To find the pod name, do the following:

1. Sign in toTableau Cloud(Link opens in a new window).

2. Navigate to your browser's address bar. The pod name is in the first portion of the URL after you've successfully signed in.

For more information about signing in to Tableau Cloud, seeSign In to Tableau Cloud(Link opens in a new window) in the Tableau Cloud Help.

About the site attribute

Thesite element of a sign in request lets you specify the site to sign in to by setting the value of thecontentUrl attribute.The content URL is the subpath of a site's full URL. In the server environment, it is referred to as theSite ID. When you sign in to Tableau Server or Tableau Cloud manually, thecontentUrl is the the value that appears after/site/ in the Browser address bar.

For example, in the following URLs, the content URL isMarketingTeam:

• 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, omitcontentUrl from thesite element,or make thecontentUrl value an empty string (contentUrl="").
• For Tableau Cloud, a sign in request must have asite element containing acontentUrl withthe value of an existing site. If these are missing, theSign In request will fail.

Response for a successful Sign In operation

If theSign 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 (whenContent-Type header is set totext/xml orapplication/xml or when theAccept header is set toapplication/xml).

<?xml version="1.0" encoding="UTF-8"?><tsResponseversion-and-namespace-settings>  <credentials token="HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3">    <sitebackground-color: #ffff00;">9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>    <userbackground-color: #ffff00;">9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />  </credentials></tsResponse>

In JSON, the response would look like the following (whenContent-Type or theAccept header is set toapplication/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"    }}

Theid attribute is the LUID, or locally unique identifier, for the site. In the preceding example, the site LUID is9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d. Many REST API methods require the site LUID to specify the site in their URI. For more information, seeIdentifying 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 thetsm configuration set command to change thewgserver.session.idle_limit setting.) If your application needs to be able to make additional calls after the credentials token has expired, you can callSign In again and get a new credentials token.

You include the credentials token as the value of theX-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, VizQL Data Service 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 HTTP403 (Forbidden) error.

When you are finished with a session, you callSign 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

(Tableau Server only)

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 auser 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" />    <userbackground-color: #ffff00;">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 credentials token. Note the following about this example:

• The code illustrates aSign In request and aSign Out request.

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

• You must substitute the name of your own server for theMY-SERVER placeholder.

• You must substitute the API version number of your own server for theversion placeholder. To find your server's API versionnumber, seeREST API and Resource Versions.

• You must substitute your own credential values in either theTOKEN_NAME andTOKEN_SECRET, orUSERNAME andPASSWORD 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-inElementTree method. For details, see theElementTree XML API(Link opens in a new window) documentation on the Python website.

For additional examples, seeREST 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.3try:# Python 3from urllib.request import urlopen, Requestexcept ImportError:# Python 2from urllib2 import urlopen, Requestimport 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 Serverversion = "x.x"     # API version of your serversite_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 inuser_name = "USERNAME"    # User name to sign in as (e.g. admin)password = "PASSWORD"# For Personal Access Token sign inpersonal_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 serverreq = Request(signin_url, data=request_data, method="POST")req = urlopen(req)# Get the responseserver_response = req.read()# Parse the response XML. The response body will look similar# to the following example:### <tsResponse>#   <credentials token="CREDENTIALS-TOKEN" >#     <site contentUrl="SITE-SUBPATH" />#   </credentials># </tsResponse>#response_xml = ET.fromstring(server_response)# Get the credentials token from the <credentials> elementtoken = response_xml.find('.//t:credentials',namespaces={'t': "http://tableau.com/api"}).attrib['token']# Get the site ID from the <site> elementsite_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 outsignout_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 aSign In request and aSign Out request.

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

• You must substitute the name of your own server for theMY-SERVER placeholder.

• You must substitute the API version number of your own server for theversion placeholder. To find your server's API versionnumber, seeREST API and Resource Versions.

• You must substitute your own credential values in either theTOKEN_NAME andTOKEN_SECRET, orUSERNAME andPASSWORD 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, seeREST 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 codeimport requests, json# NOTE! Substitute your own values for the following variablesuse_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 Serverversion = "x.x"     # API version of your serversite_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 inuser_name = "USERNAME"    # User name to sign in as (e.g. admin)password = "{PASSWORD}"# For Personal Access Token sign inpersonal_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 serverreq = requests.post(signin_url, json=payload, headers=headers, verify=False)req.raise_for_status()# Get the responseresponse = 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 elementtoken = response["credentials"]["token"]# Get the site ID from the <site> elementsite_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 outsignout_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!')