Managing API tokens

API tokens overview

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

The Tanium Server generates and stores a token in response to an API request. The token is bound to the user account 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 user.

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 Tanium Server 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.

To manage API tokens, users require a role with the micro admin permissions View Token, Use Token, and Revoke Token. The Administrator reserved role has these permissions.

View API tokens

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 > Configuration > 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 on the Tanium Server 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 API tokens

  1. From the Main menu, go to Administration > Configuration > API Tokens.
  2. 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.

      To change the default expiration interval (seven days), see Set the default expiration interval for API tokens.

    • Trusted IP addresses: Enter the IP addresses of the systems from which you will use this token to authenticate with the Tanium Server. Use commas or line breaks to separate multiple entries.

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

  3. Click Save and review the token details.
  4. (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 on the Tanium Server 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 configure the api_token_trusted_ip_address_list global setting with the systems from which users are allowed to use API tokens to access the Tanium Server. Users can use tokens from any of the systems that you specify in this setting. To allow the use of specific API tokens from additional systems, specify the systems when you create the tokens (see Create API tokens).

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 > Management > Global Settings.
  2. Select the api_token_trusted_ip_address_list setting and, in the Selected System Setting pane, click Edit.
  3. Populate the Setting Value with the IP addresses of the host systems from which users will use tokens to access the Tanium Server. Use commas to separate the entries, such as 192.0.2.1,192.0.2.2.
  4. Click Save.

Set the default expiration interval for API tokens

By default, API tokens expire one week after you create them. Changes to the default expiration 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:

  1. From the Main menu, go to Administration > Management > Global Settings.
  2. Select the api_token_expiration_in_days setting and, in the Selected System Setting pane, click Edit.
  3. Set the Setting Value to the desired expiration interval 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 > Configuration > 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.