Docs » Administer Your Organization » Authentication Tokens

Authentication Tokens 🔗

Authenticate using tokens 🔗

Use authentication tokens to authenticate Splunk Infrastructure Monitoring API requests, and track API usage, and control your use of resources.

Infrastructure Monitoring has two types of tokens:

User API access tokens 🔗

Authenticate Infrastructure Monitoring API requests with a user api access token (session token). Obtain a user api access token from your profile page. User API access tokens expire after 30 days.

Some API requests require a User API access token associated with an organization user who has administrative access. These users are known as administrators. To learn more, see Administrator User API access tokens.

If you’re sending data to Infrastructure Monitoring, you can’t use a User API access token in your API request. Instead, you need to use an access token.

Administrator User API access tokens 🔗

The following API requests require a User API access token associated with an administrator:

API Task
Integration Create, update, delete, or validate an integration
Org token Create, update, or delete an org (access) token, or rotate an org token secret
Dashboards and dashboard groups Change or remove write permissions for a user other than yourself
Detectors Change or remove write permissions for a user other than yourself
Organizations

The following API requests require a User API access token associated with an administrator:

  • Retrieve information for your organization
  • Retrieve information for one or more organization users
  • Create, update, or delete a custom metric category
  • Invite a user to your organization
  • Invite a group of users to your organization
  • Grant administrative access to a user
  • Delete a user from your organization
Teams Create, update, or delete a team, or remove a team member other than yourself.

Even if you’re not an administrator, you can manage permissions on items for which you already have permissions.

If you’re an administrator, you can see how a user created or updated an object using a particular User API access token by selecting Info from the object’s Actions menu.

For example, to see information for a dashboard, select Dashboard > Info from the dashboard’s Actions menu.

To track API calls by user, ask your users to obtain and use their own User API access token. If the token expires, they can generate another one on their profile page.

Create a User API access token 🔗

To create a User API access token, do the following:

  1. Open the Settings menu at the far right of the navigation bar.
  2. Select My Profile, then click Generate User API Access Token.
  3. Click Show User API Access Token.
  4. To copy the token, click Copy.
  5. After you copy the token, click Hide to prevent others from seeing the token.

After you generate and copy the User API access token, you can’t see it again in your profile. Instead, generate a new token. You can generate as many as you want.

You don’t need to delete your User API access tokens. Instead, you can let them expire.

Access tokens 🔗

Access tokens, also known as org tokens, are long-lived organization-level tokens. By default, these tokens persist for 5 years, so you can use them in API calls that continually send data points to Infrastructure Monitoring. You can also use them in any continually-running scripts that call the API.

You can also use access tokens to track usage for different groups of users. This feature helps you track and manage your resource usage. For example, if you have users in the U.S. and Canada sending data to Infrastructure Monitoring, give each group its own specific access token. You can then compare the amount of data coming from each country.

You can’t use access tokens for API requests listed in the section Administrator User API access tokens.

Note

All access tokens are available to any user in your organization, so you can’t restrict access to specific tokens. Instead, use your company’s security and management procedures to let users know which token you want them to use.

The default access token 🔗

By default, every organization has one organization-level access token. If you don’t create any additional tokens, every API request that sends data to Infrastructure Monitoring must use this access token.

Manage access tokens 🔗

To manage your access (org) tokens, do the following:

  1. Open the Settings menu at the far right of the navigation bar.
  2. Hover over Organization Settings, then select Access Tokens.
  3. To find an access token in a large list, start entering its name in the search box. Infrastructure Monitoring returns matching results.
  4. To look at the details for an access token, click the expand icon to the left of the token name.
  5. If you’re an organization administrator, the Actions menu appears at the right side of the token listing. You can select token actions from this menu.

View and copy access tokens 🔗

To view the value of an access token, click the token name and then click Show Token.

To copy the token value, click Copy. You don’t need to be an administrator to view or copy an access token.

Create an access token 🔗

Note

To perform the following tasks, you must be an organization administrator.

To create an access token, do the following:

  1. Click New Token on the Access Tokens pane.

  2. Provide a name for the new token.

  3. Click OK.

    The name must be unique. If you enter a token name that is already in use, even if the token is disabled, Infrastructure Monitoring won’t accept the name.

Rename an access token 🔗

To rename a token, do the following:

  1. Select Rename Token from the token’s Actions menu.

  2. Enter a new name for the token.

  3. Click OK.

    Renaming a token has no effect on the value of the token.

Disable or enable an access token 🔗

Note

You can’t delete tokens, you can only disable them.

To disable a token, do the following:

  1. Select Disable from the token’s Actions menu.
  2. The line that displays the token has a shaded background, which indicates that the token is disabled.

The UI displays disabled tokens at the end of the tokens list, after the enabled tokens.

To re-enable a disabled token, do the following:

  1. Select Enable from the disabled token’s Actions menu.
  2. The line that displays the token has a light background, which indicates that the token is enabled.

Manage resource usage with access tokens 🔗

If you have Infrastructure Monitoring Enterprise Edition, you can manage costs associated with sending in data by setting limits on access tokens.

Regardless of the edition you’re using, access tokens also help you control the rate at which you use Infrastructure Monitoring resources. This feature helps you provide good performance in the user interface.

Set up access token limits and alerts 🔗

To set token limits, do the following:

  1. Select Manage Token Limit from the token’s actions menu.
  2. The Manage Token Limits options appear. Depending on your pricing model, you see up to four cost-related token limits you can set. You can also set the Job Start Rate and Event Search Rate rate-related limits.
  3. Enter a value for the limit or limits you want to set.
    • For cost-related limits, to remove an existing limit, click Remove Limit.
    • For rate-related limits, to remove an existing limit, delete everything from the text box.
  4. To send a notification to recipients when a cost-related usage exceeds one of the limits, click Add Recipient and select the recipient or notification method you want to use. To learn more about notifications for limits, see Notifications for cost-related limits.

Click Update.

Set up custom alerts for use with access tokens 🔗

You can create a regular detector to set up an alert for a token when its usage has reached a different level than 90%. You can also use a detector to monitor resource usage by a token if the resource isn’t part of the limits provided by Infrastructure Monitoring.

You can’t set up alerts or notifications for rate-related token limits.

To track token usage, use one of the following metrics:

In your detector, filter these metrics using the property tokenName to identify the token you want to monitor.

Manage resource usage for a team 🔗

To manage resource usage by team, do the following:

  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 Infrastructure Monitoring.

Monitor access token usage 🔗

To see usage status for an access token, do the following:

  1. Navigate to your profile page.
  2. In the area that lists your organization, click Access Tokens.
  3. Click the token name. The details for the token appear. The display is specific to your pricing model and the limits you’ve set.

Tokens can be Above Limit, Close to Limit, or Below Limit. Token status Close to Limit if the usage of any of its limits is greater than or equal to 90%.

The usage status is the status of the usage that’s 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 the usage for the token as Above Limit if the Hosts usage is above its limit, even if the Custom Metrics value is below its limit.

To view usage values for a token, hover over its usage status.

To display more detailed information for the token, click the token name. If API requests are using the token to send data to Infrastructure Monitoring, a chart appears that shows how much ingest levels in for the past seven days for each usage limit. The chart displays data at a one-hour resolution. Infrastructure Monitoring monitors the token whether you set limits for the token or not.