Personal Access Tokens

Applies to: Tableau Cloud, Tableau Server

Personal access tokens (PATs) provide Tableau Server users the ability to create long-lived authentication tokens. The tokens allow users to run automation with Tableau REST APIs without requiring hard-coded credentials or interactive signin. More information about using personal access tokens with Tableau REST APIs is at Signing In and Out (Authentication)(Link opens in a new window).

Personal access tokens are not used for generic client access to the Tableau Server web interface or TSM. To use personal access tokens with tabcmd, install the new version of tabcmd from https://tableau.github.io/tabcmd/.

We recommend creating personal access tokens for automated scripts and tasks that are created with Tableau REST API:

  • Improve security: Personal access tokens reduce risk in the event credentials are compromised. In the case where Tableau Server uses Active Directory or LDAP as an identity store, you can reduce the scope of credential compromise by using a personal access token for automated tasks. In this case, using an application-specific token doesn't expose the broader system in the event that automation or script files are compromised. If a token gets compromised or is used in automation that is failing or posing a risk, you can just revoke the token. You do not need to rotate or revoke the user's credentials.
  • Audit and track: As an administrator, you can review Tableau Server logs to track when a token is used, what sessions are created from that token, and the actions that are performed in those sessions. You can also determine if a session and the related tasks were performed from a session that was generated from a token or from an interactive signin.
  • Manage automation: A token can be created for each script or task that is run. This allows you to silo and review automation tasks across your organization. Additionally, by using tokens then password resets or metadata changes (username, email, etc.) on user accounts will not disrupt automation as it would when credentials are hard-coded into the scripts.

Understand personal access tokens

When a token is created, it is hashed then stored in the repository. After the token is hashed and stored, the original token is deleted. Users are instructed to copy the token to a safe place and to handle it as they would a password. When the token is used at run-time, Tableau Server hashes the token presented by the user and compares it to the hashed value stored in the repository. If a match is made, then an authenticated session is started.

Note: One personal access token is required per concurrent request. Signing in again with the same access token, whether at the same site or a different site, will terminate the previous session and result in an authentication error.

In the context of authorization, Tableau Server handles the authenticated session with same permissions and rights that the user has as an interactive user.

Server administrator impersonation

Beginning with version 2021.1, you can enable Tableau Server personal access token impersonation. In this scenario, access tokens that are created by server administrators can be used for user impersonation(Link opens in a new window) when using the Tableau Server REST API. Impersonation is useful in scenarios where you are embedding end-user-specific Tableau content within your application. Specifically, impersonation access tokens allow you to build applications that query as a given user and retrieve content that the user is authorized for within Tableau Server, without hard-coding any credentials.

For more information, see the Tableau REST API Help section, Impersonating a User(Link opens in a new window).

Enable Tableau Server to accept personal access tokens during impersonation sign-in requests

By default, Tableau Server does not allow impersonation for server administrator personal access tokens. You must enable the server-wide setting by running the following commands.

tsm authentication pat-impersonation enable [global options]

tsm pending-changes apply

Important: After you have run the commands, all personal access tokens created by server administrators (including preexisting tokens) can be used for impersonation. To bulk-revoke all existing server administrator personal access tokens, you can post the DELETE /api/{api-version}/auth/serverAdminAccessTokens URI. See the Tableau REST API Help section, Impersonating a User(Link opens in a new window).

Create tokens

Users with accounts on Tableau Server can create, manage, and revoke personal access tokens on the My Account Settings page. See ManageYour Account Settings(Link opens in a new window) in the Tableau Desktop and Web Authoring Help for more information.

Users must create their own personal access tokens. Administrators cannot create tokens for users.

Token expiry

Personal access tokens will expire if they are not used after 15 consecutive days. If they are used more frequently than every 15 days, an access token will expire after 1 year. After a year, you must create a new token. Expired personal access tokens will not display on the My Account Settings page.

You can change refresh token expiry time span using the refresh_token.absolute_expiry_in_seconds option with the tsm configuration set command.

Revoke users' tokens

Users are able to revoke their own tokens on the My Account Settings page. As an administrator, you can also revoke personal access tokens.

  1. Sign in to the Tableau Server Admin Area as a site administrator or server administrator.
  2. Locate the user whose token you want to revoke. For more information about navigating Server Admin pages and locating users, see View, Manage, or Remove Users.
  3. Click the user's name to open their profile page.
  4. On the user's profile page, click the Settings tab.
  5. In the Personal Access Tokens section, identify the token that you want to revoke and then click Revoke.
  6. On the verification pop-up, click Delete.

Track and monitor usage

All token-related actions are logged in the Tableau Server Application Server (vizportal) service.

To locate token-related activities, filter log entries containing the string, RefreshTokenService.

Tokens are stored in this format :Token Guid: <TokenID(Guid)>, where the TokenID is a base64 encoded string. The token secret is not included in the logs. For example:

Token Guid: 49P+CxmARY6A2GHxyvHHAA== (e3d3fe0b-1980-458e-80d8-61f1caf1c700).

The following is an example snippet of two log entries. The first shows how a user is mapped to a token.The second shows a refresh event for the same token:

RefreshTokenService - Issued refresh token to the following user: jsmith. Token Guid: 49P+CxmARY6A2GHxyvHHAA== (e3d3fe0b-1980-458e-80d8-61f1caf1c700)
RefreshTokenService - Redeemed refresh token. Token Guid: 49P+CxmARY6A2GHxyvHHAA== (e3d3fe0b-1980-458e-80d8-61f1caf1c700)

To locate key operations, filter log entries containing the string, OAuthController.

Back to top
Thanks for your feedback!