Managing API tokens

API tokens overview

Tanium REST API authentication tokens enable user and service accounts to establish long-lived sessions with Tanium Cloudthe Tanium Server without repeatedly re-authenticating for workflows that are long-lived but not continuously running. For example, the service account for a module might periodically access Tanium Cloudthe Tanium Server for updates to computer groups that the module targets for actions.

Tanium Cloud The Tanium Server generates and stores a token in response to an API request. The token is bound to the user and persona that sent the request. Each user can have multiple tokens. A token can authenticate only the user who requested it, not other users. The authentication credentials and authorization permissions of a token are those of the requesting persona.

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. Contact Tanium Support for access to the REST API Reference that contains procedures for manually or automatically requesting and revoking tokens through the API. You can also see and manually revoke tokens through the Tanium Console, as described in the following sections.

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 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 string, select the token in the grid and click View Token.

    You cannot view the token string 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

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

    The authentication credentials and authorization permissions of a token are those of the requesting persona. To limit access to computer groups and content sets, create a persona with the desired permissions and then sign in with the new persona.

  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 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. (Optional) 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 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.

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,

    To enable any system to use tokens, enter 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.