Authentication Methods

Using the authentication methods of the Tableau Server REST API you can:

  • Sign in a user to a Tableau server
    • Authenticate with a Personal Access Token(Link opens in a new window) (PAT) for improved security with granular monitoring and revocation
    • Authenticate with username and password for quick manual sign in for all users and user impersonation for administrators
    • Impersonate a user if you are an administrator, using username and password or PAT.
  • Sign out a user from a Tableau server
  • Switch the from the current site you are signed into, to another on the server without authenticating again

This functionality relates to the UI elements and concepts described at: Sign in to Tableau Server or Online(Link opens in a new window).



The Tableau Server Client library(Link opens in a new window), a Python wrapper for the REST API, offers the following related items: Auth Methods(Link opens in a new window); and Sign In and Out(Link opens in a new window).

Revoke Administrator Personal Access Tokens

Revokes all personal access tokens(Link opens in a new window) (PATs) created by server administrators. This method is not available for Tableau Online.

URI

DELETE /api/api-version/auth/serverAdminAccessTokens

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

Only Tableau Server users with server administrator permissions can use this method.

Response Code

204

Response Body

None

Version

Version 3.11 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Revoke server admin tokens forbidden, The user does not have the server administrator permissions required to call this method.
404 404000 Server not found The Tableau Server in the URI doesn't correspond to an existing server.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Sign In

Signs you in as a user on the specified site on Tableau Server or Tableau Online. This call returns a credentials token that you use in subsequent calls to the server. Typically, a credentials token is valid for 240 minutes. With administrator permissions on Tableau Server, you can change this timeout by using the tsm configuration set(Link opens in a new window) command and setting the wgserver.session.idle_limit option.

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.

If you are a Tableau Server administrator , you can use your username and password to sign in and impersonate a specific user. You might do this if you want manage sign in using a centralized delegation strategy. User impersonation is not available for Tableau Online sites.

For more information about authentication, see Signing In and Signing Out (Authentication).

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.

URI

POST /api/api-version/auth/signin

Note: 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/api-version/auth/signin

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.

Request Body

Signing in with a user's personal access token (PAT): 

<tsRequest>
  <credentials personalAccessTokenName="personal-access-token-name"
    personalAccessTokenSecret="personal-access-token-secret" >
      <site contentUrl="content-url" />
  </credentials>
</tsRequest>
        

Signing in with a user's user name and password:

<tsRequest>
  <credentials name="username" password="password" >
    <site contentUrl="content-url" />
  </credentials>
</tsRequest>
        

Signing in with server administrator's username and password to impersonate a user (not available for Tableau Online):

<tsRequest>
  <credentials name="username" password="password" >
	<site contentUrl="content-url" />
	<user id="user-to-impersonate" />
  </credentials>
</tsRequest>
        

Signing in with server administrator's personal access token(Link opens in a new window) (PAT) to impersonate a user (not available for Tableau Online):

<tsRequest>
  <credentials personalAccessTokenName="personal-access-token-name"
    personalAccessTokenSecret="personal-access-token-secret" >
	  <site contentUrl="content-url" />
	  <user id="user-to-impersonate" />
  </credentials>
</tsRequest>
      

Attribute Values

personal-access-token-name

The name of the personal access token when signing in with a personal access token. The token name is available on a user’s account page on Tableau server or online.

personal-access-token-secret

The secret value of the personal access token when signing in with a personal access token. The value of the token secret is available only in the dialog that appears when a user creates a personal access token(Link opens in a new window).

username The name of the user when signing in with username and password. The name and password in the <credentials> element can represent any user in the specified site. If the user is not an administrator, they might have limited permissions to perform subsequent operations.

Note: If the server is configured to use Active Directory authentication, and if the user name is not unique across domains, you must include the domain as part of the user name (for example, domain_name\Adam).

password The password when signing in with username and password.
content-url The URL of the site to sign in to.

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, or 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, it is required that a site element containing a contentUrl with the value of an existing site be specified in a sign in request. If these are missing, the Sign In request will fail.

user-to-impersonate The LUID of a user to sign in as. For impersonation when a system administrator signs in with user name and password.

Permissions

Any Tableau user can sign in through the REST API. A user that does not have administrator permissions will have limited permissions to perform subsequent operations. Only server administrators can sign in with username and password in order to impersonate other Tableau Server users.

Response Code

200

Response Body

<tsResponse>
  <credentials token="authentication-token"
	  estimatedTimeToExpiration="time-to-expiration" >
	    <site id="site-id" contentUrl="content-url" />
	    <user id="user-id-of-signed-in-user"
  </credentials>
</tsResponse>
        

An estimatedTimeToExpiration value is returned when you sign in using a PAT. The value represents the approximate time until the token returned from the PAT sign in will expire and need to be refreshed. The estimated time is based on regular usage of the token for authenticating calls, but actual time may be shorter if the token is unused for an extended length of time.

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains both username/password and a personal access token, or contains malformed XML.
401 401001 Login error The credentials (name or password, or personal access token name or secret) are invalid for the specified site, or the site content URL is invalid.
401 401001 Login error Login is blocked because several requests with invalid credentials were made.
401 401001 Login error The Administrator has requires the user to update their password.
401 401001 Login error The password has expired.
405 405000 Invalid request method Request type was not POST.

If you are signing in to a Tableau online site, this error may be caused by leaving the pod name out of the server address in the URI.

The error can also be caused by attempting to make a request to a SSL-protected server using HTTP, rather than HTTPS.

For more information, see Handling Errors.

Example

curl "https://MY-SERVER/api/3.13/auth/signin" -X POST -d @signin.xml

Content of signin.xml:

<tsRequest>
  <personalAccessTokenName="MY_PAT_NAME"
	personalAccessTokenSecret="vFel4qtGTZ2+Po0ZWT7YWg==:nMmSHnQ5kJBP17ZtsBgPtuVWdYJFAbBG"  >
      <site contentUrl="MarketingSite" />
  </credentials>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
    <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
          contentUrl="MarketingSite"/>
  </credentials>
</tsResponse>

Sign Out

Signs you out of the current session. This call invalidates the authentication token that is created by a call to Sign In.

URI

POST /api/api-version/auth/signout

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

Any user can call this method.

Response Code

204

Response Body

None

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.13/auth/signout" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Switch Site

Switches you onto another site without having to provide a user name and password again.

This method allows an authenticated user to switch sites that they have access to. When you call this method, you must provide the current authorization token as the value of the X-Tableau-Auth header. Using the current authentication token, the method signs you in as a user on the site specified in the request payload. The method returns a new authentication token and invalidates the old one. You have the permissions of the user associated with the authorization token. 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.)

Note This method is not available on Tableau Online.

URI

POST /api/api-version/auth/switchSite

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.

Request Body

<tsRequest>
   <site contentUrl="content-url" />
</tsRequest>
          

Attribute Values

content-url The URL of the site to switch to (the destination).

Note: The content URL is not the site name. Instead, the content URL is the value that in the server environment is referred to as the Site ID. The content URL used in this method is not the site ID LUID that's included in other methods.

To determine the value to use for the contentUrl attribute, sign in to Tableau Server and examine the value that appears after /site/ in the URL. For example, in the following URLs, the content URL is MarketingTeam:

http://MyServer/#/site/MarketingTeam/projects

For Tableau Server, if the contentUrl attribute is an empty string, you are signed in to the default site. Note that you always sign in to a specific site, even if you don't specify a site when you sign in.

Permissions

Tableau Server users who are not server administrators can switch sites, provided that they have access to the destination site.

Response Code

200

Response Body

<tsResponse>
  <credentials token="authentication-token" >
    <site id="site-id" contentUrl="content-url" />
    <user id="user-id-of-signed-in-user" />
  </credentials>
</tsResponse>
        

Version

Version 2.6 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authentication credentials were provided.
401 401002 Unauthorized access Invalid authentication credentials were provided.
401 401003 Switch site error There was a problem switching sites. The site might be unavailable or is not found.
403 403070 Cannot switch to the same site The site specified as the destination site is also the current site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "https://MY-SERVER/api/3.13/auth/switchSite" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"-d @switch_site.xml

Content of switch_site.xml:

<tsRequest>
   <site contentUrl="MarketingSite" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <credentials token="9a8b7c6d5e4f3a2b1c0d1e2f3a4b5c6d">
    <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
          contentUrl="MarketingSite"/>
  </credentials>
</tsResponse>


Thanks for your feedback!