Managing API tokens

API tokens overview

Tanium REST API authentication tokens enable user and service accounts to establish long-lived sessions with TaaSthe 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 TaaSthe Tanium Server for updates to computer groups that the module targets for actions.

TaaS 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.

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.

      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 TaaSthe 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. (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 > Platform Settings.
  2. In the Name column, click api_token_trusted_ip_address_list.
  3. Populate the 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.

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

  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 > Configuration > Platform Settings.
  2. In the Name column, click api_token_expiration_in_days.
  3. Set the 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 > 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.