Managing API tokens

Tanium as a Service automatically manages Tanium REST 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. In Tanium Core Platform 7.3 or later, you can configure custom modules and API user accounts to use tokens, but not the current set of Tanium-provided modules. Future Tanium modules that are designed for version 7.3 or later will support tokens.

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. For the procedures to manually or automatically request and revoke tokens through the Tanium Server REST API, ask your Tanium Technical Account Manager (TAM) for access to the Tanium Server REST API Reference. 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

From the Main menu, select Console > Configuration > Authentication > API Tokens to see a list of valid and expired API tokens. Valid tokens appear in regular text, while expired tokens are grayed out. 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.

Enable API tokens

You must whitelist the systems from which users with API tokens will access the Tanium Server.

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

  1. From the Main menu, select Console > Administration > 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. Save your changes.

Set the expiration interval for API tokens

By default, API tokens expire one week after you create them. Changes to the 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, select Console > Administration > 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.
  4. Save your changes.
  5. Verify your change:
    1. Create a new token (consult your TAM for the steps).
    2. From the Main menu, select Console > Configuration > Authentication > API Tokens.
    3. Verify that the Expiration Time for the new token reflects the changed setting.

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, select Console > Configuration > Authentication > API Tokens.
  2. Select one or more API tokens and click Revoke.

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