Docs » Administration » Managing Tokens

Managing Tokens

Note

This information on this page applies to you only if your organization’s subscription plan is based on the number of hosts or metrics that SignalFx is monitoring for you. If your organization’s usage is based on the rate at which you are sending datapoints to SignalFx (DPM), see Track Organization DPM Usage with Access Tokens.

Tokens Overview

Tokens are used to authenticate and track various types of usage in SignalFx. As an administrator, you can provide instructions or guidance to your users regarding which token to use for different use cases.

SignalFx supports two types of tokens – user API access tokens and organization-level access tokens.

User API access tokens

User API access tokens (sometimes called session tokens) are created by an authentication request from a specific user on their profile page, and expire automatically after 30 days. These tokens can be used to access most capabilities in the SignalFx API, but cannot be used to send ingest data (datapoints or custom events) to SignalFx. Administrators must use this type of token to perform the following tasks via the API:

  • Configure integrations
  • Create and manage access tokens
  • Override write permissions (Note that anyone can use their API access token to manage permissions on items for which they already have permissions.)
  • Create/delete teams, add/remove team members (Note that anyone can join or leave a team, but only admins can add/remove other users)
  • Manage users
  • Manage global data links
  • Add suggested search filters for use in the Metrics Sidebar
  • View certain organization-related information in the UI (Organization Overview, Billing and Usage) and download usage reports
  • Make changes to your organization’s subscription plan

When someone uses a User API access token to create or update UI objects such as dashboards, charts, and detectors, you can see who created or most recently updated a particular object. For example, to see that information for a dashboard, select Dashboard -> Info from the dashboard’s actions menu.

../_images/dashboard-info.png

If you want to track this information, tell your users to use their User API Access Token when working in the API. If their token expires, they can just generate another one on their profile page. If this information isn’t important to you, users can simply use an organization-level access token, described below, when using the API for tasks other than those listed above.

Access tokens

Access tokens (sometimes called org tokens) are long-lived organization-level tokens. By default, these tokens persist for 5 years, and thus are suitable for embedding into emitters that send data points over long periods of time, or for any long-running scripts that call the SignalFx API.

This type of token can be used for any API actions except those listed in User API access tokens above.

Access tokens can track usage for different groups of users. This feature can help you manage how your usage metrics are being utilized. For example, you may have users in the U.S. and Canada sending data to SignalFx. If each group of users uses a specific access token when sending data, you can compare the amount of data coming from each region.

Note

All access tokens are available to any user in your organization. That is, you cannot restrict who has access to which tokens. Use standard administrative processes in place in your organization to let people know which token you want them to use.

You can also use multiple access tokens to limit usage for a token; for more information, see Managing usage limits with access tokens.

Working with access tokens

To view and manage access tokens, open the Settings menu at far right on the navigation bar, hover over Organization Settings, and then select Access Tokens. The following illustration shows the Access Tokens pane as well as options available on a token’s Actions menu. Only administrators see the Actions menu.

../_images/hb-tokens.png

About the default access token

By default, every organization has one organization-level access tokens. If you don’t create any additional tokens, everyone in your organization sending data to SignalFx will use this access token.

View and copy an access token

To view an access token, click the token name and then click Show Token. Then click Copy to copy the token. You do not need to be an administrator to view or copy a token.

../_images/click-show-token.png

Create an access token

To create access tokens to track usage in your organization, click New Token on the Access Tokens pane. You’ll be asked to provide a name for the new token. Token names must be unique; if you enter a name that is already being used (even for a disabled token), it will not be accepted.

../_images/new-token.png

Rename an access token

To rename a token, select Rename Token from the token’s Actions menu. Renaming a token has no effect on the value of the token.

Disable and enable access tokens

To disable a token, select Disable from the token’s Actions menu. (You cannot delete tokens.)

Disabled tokens are shown at the bottom of the tokens list, below the enabled tokens. To re-enable a disabled token, select Enable from the disabled token’s Actions menu.

Managing usage limits with access tokens


Available in SignalFx Enterprise Edition


In addition to just tracking usage for different users, you can use access tokens to prevent plan overages by limiting usage for a token, and to send alerts when usage for a token reaches a specified level. For example, your subscription plan may support sending 5,000 custom metrics. You may have some hosts that you use only for specific testing purposes, and you don’t want data sent from those hosts to count significantly towards the number of custom metrics you are monitoring. You can create a token with a limit of, say, 100 custom metrics and then configure those hosts to send data using that token. This ensures that your production hosts always have at least 4,900 custom metrics available.

Setting up limits and alerts for use with access tokens

For each access token, you can set a limit for the number of hosts, containers, custom metrics, and high-resolution metrics can be sent using that token. To do so, select Manage Token Limit from the token’s actions menu.

../_images/hb-tokens.png

The Manage Token Limits options are displayed. (Note that if your subscription plan is usage based, you will see options to set token limits only for custom and high-resolution metrics.)

../_images/token-manage-limit.png

Specify the limits for each usage metric.

Token limits are used to trigger an alert that notify one or more recipients when the usage has been above 90% of the limit for 5 minutes. To specify the recipients, click Add Recipient, then select the recipient or notification method you want to use. (Specifying recipients is optional but highly recommended.) The severity for token alerts is always Critical.

Click Update.

What happens when a limit is reached?

When a token is at or above its limit in a usage category, new metrics for that usage category will not be stored and processed by SignalFx.

For example, if you have specified a token limit for number of hosts and SignalFx has recently received data from a specific host, then you will continue to see data from that host, even while the token is being limited. However, data for new hosts will not be processed and stored, and charts and detectors that would be expected to include that data will not do so.

Setting up custom alerts for use with access tokens

You can create a regular detector if you want to set up an alert for a token when its usage has reached a different level than 90%, or if you want alerts for tokens that don’t have a limit. The metrics that track token usage are listed below. In your detector, these metrics can be filtered using the property tokenName for the token in question.

Managing usage for a team

For teams that are sending data to SignalFx, you can manage usage per team with access tokens.

  1. Create a token you want team members to use.
  2. Set limits for the token.
  3. Tell team members to use the specified token when sending data to SignalFx.

Monitoring usage for a token

Usage status for a token is shown on the tokens page. A token can be Above Limit, Close to Limit, or Below Limit. A token is considered Close to Limit if the usage of any of its metrics is greater than or equal to 90%.

The usage status reflects the status of the usage metric closest to its limit. For example, suppose you have set limits for both Hosts and Custom Metrics for a token. The tokens page will show its usage as Above Limit if the Hosts usage is above its limit, even if the Custom Metrics value is below its limit, and vice versa.

To view usage values for a token, you can hover over its usage status. In this illustration, the token has not yet been used to send any data to SignalFx, so all its values are zero.

../_images/token-hover.png

To display more detailed information about usage for the token, click the token name. If the token is being used to send data to SignalFx, a chart will show values for how much data has been coming in for the past seven days for each usage metric. Data is displayed at one-hour resolution. Note that the monitoring will operate whether you have set any limits for the token or not.