Managing API tokens

API tokens overview

Tanium REST API authentication tokens enable users to establish long-lived sessions with Tanium Cloudthe Tanium Server without repeatedly re-authenticating for workflows that are long-lived but not continuously running.

A token can authenticate only the user who creates it, not other users. The authentication credentials and authorization permissions of a token are those of the user account or persona that is used to create it. Each user or persona can have multiple tokens.

Tokens have a configurable expiration interval. To prevent interruptions to long-lived workflows, users must rotate tokens: request new tokens and revoke the current ones before they expire.

For the user role permissions that are required to manage API tokens, see Manage API tokens.

To troubleshoot issues with API tokens, see Tanium Core Platform Deployment Reference Guide: Authentication logs.

View API token details

The API Tokens page displays the attributes of valid API tokens. The API Tokens grid stops displaying tokens that you revoke. The grid identifies each token by its ID (this column is hidden by default) and indicates the User for whom the token is valid.

  1. From the Main menu, go to Administration > Permissions > API Tokens.

    The page displays token attributes but not token strings.

    API tokens

  2. (Optional) To display a token value, select the token in the grid and click View Token.

    You cannot view the token value in the Tanium Console after:
    • The visibility timeout expires (five minutes)
    • You refresh the API Tokens page or grid
    • You navigate to another Console page

  3. (Optional) Use the filters to find specific tokens:
    • Filter by text: To filter the grid by any column values, enter a text string in the Filter items field.
    • Filter by attribute: Filter the grid by one or more attributes, such as the user for whom the token is valid. Expand the ExpandFilters section, click Add Add, select an attribute and operator, enter a text string that contains all or part of the attribute value, and click Apply. If you add multiple attribute filters, the Boolean AND operator applies. After you finish specifying attributes, click Apply All to filter the grid.

Create an API token

Every token has the same authentication credentials and authorization permissions as the user account or persona that you use to create the token. Therefore, perform the following steps through an account or persona that has the same limits as the token must have in terms of accessing computer groups and content sets. See Managing users and Managing personas.

To extend the expiration period of a token without changing its other settings, you can Rotate an API token.

  1. Sign in to the Tanium Console as the user and persona for whom you want to create a token.

  2. From the Main menu, go to Administration > Permissions > API Tokens.
  3. Click New API Token and configure the token settings:
    • Notes (optional): Enter a description of the purpose for this token.
    • Expire in days: Enter the expiration interval. By default, the maximum interval is 365 days. If you do not enter a value, the interval defaults to 7 days.

      To change the default interval or maximum interval, see Configure token expiration settings.

    • Trusted IP addresses: Enter the external IP addresses of the systems from which you will use this token to authenticate with Tanium Cloudthe Tanium Server. Use commas or line breaks to separate multiple entries.
      To enable any system to use the token, enter 0.0.0.0/0. However, for security, enable the token for all systems only in a non-production environment.

      To specify systems from which you can use any token, see Enable systems to use API tokens.

  4. Click Save and review the token details.
  5. Copy Copy the token to your clipboard if you want to record it for future reference, and then click Close.

    You cannot view the token value in the Tanium Console after the visibility timeout (five minutes) expires, or you refresh the API Tokens page or grid, or you navigate to another Console page. If you later rotate the token, you must re-enter its value. Therefore, if you want rotation to be an option, copy the value before the timeout and save it in a secure location.

Rotate an API token

To extend the expiration interval of a token without changing any of its other settings, rotate the token. Rotation deletes the existing token and creates a new one. The expiration timer of the new token is reset and has the same interval as the deleted token.

You cannot rotate a token unless you saved a record of its value after creating the token. After you rotate the token, the visibility timeout for its value resets to five minutes. See View API token details.

  1. Sign in to the Tanium Console as a user who has the Token - Rotate permission.

  2. From the Main menu, go to Administration > Permissions > API Tokens.

  3. Select the token and click Rotate Token.

  4. Enter the Token value and click Confirm.

  5. Copy Copy the new token value to your clipboard if you want to record it for future use (such as for rotating the token again), and then click Close.

Enable systems to use API tokens

Perform this task to specify from which systems users are allowed to use API tokens to access the Tanium Server. To allow the use of specific API tokens from additional systems, specify those systems when you create the tokens (see Create an API token).

By default, the Tanium Server allows token requests from the Tanium Module Server, so you do not have to add the Module Server to the allow list.

  1. From the Main menu, go to Administration > Configuration > Settings > Advanced Settings.
  2. In the Name column, click api_token_trusted_ip_address_list.
  3. Populate the Value with the external IP addresses of the host systems from which users will use tokens to access the Tanium Server, and then click Save. Use commas to separate the entries, such as 192.0.2.1,192.0.2.2.

    To enable any system to use tokens, enter 0.0.0.0/0. However, for security, apply this option only in a non-production environment.

  4. Enable the setting authenticate_api_token_with_x_forwarded_for_ip only if all API token access to the Tanium Server must go through a reverse proxy server. If authenticate_api_token_with_x_forwarded_for_ip is disabled in such deployments, the api_token_trusted_ip_address_list setting cannot restrict which systems are allowed access.

    1. In the Name column, click authenticate_api_token_with_x_forwarded_for_ip.

    2. Set the Value to 1 and click Save.

Configure token expiration settings

By default, API tokens expire one week after you create them if you did not specify the expiration interval during token creation. Also by default, you cannot specify an interval beyond 365 days during token creation. You can change both the default interval and maximum interval. However, changes to the default interval apply only to tokens that are created after you change the setting; you cannot change the interval for existing tokens. Perform the following steps to change the expiration interval settings:

  1. From the Main menu, go to Administration > Configuration > Settings > Advanced Settings.
  2. To change the default expiration interval, click api_token_expiration_in_days in the Name column, set the Value to a new interval (in days), and click Save.
  3. To change the maximum expiration interval, click api_token_max_expiration_in_days in the Name column, set the Value to a new maximum (in days), and click Save.

Revoke API tokens

You might want to revoke an API token if you have doubts about its security or if its associated user is no longer with your organization.

  1. From the Main menu, go to Administration > Permissions > API Tokens.
  2. Select one or more API tokens, click Delete Selected Delete Selected, and Confirm the operation.

    The revoked tokens no longer appear in the API Tokens grid.