SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Org Tokens API

API for creating, retrieving, updating, and deleting an organization's org tokens

If you're an Enterprise customer, this API also lets you set limits and thresholds for org tokens. When you do this, the org token controls the amount of data the /datapoint and /backfill endpoints can send to SignalFx.

Overview

When you send a request to store metrics using the endpoint https://ingest.{REALM}.signalfx.com/v2/datapoint, you have to authenticate the request with an org token. In the web UI, these are called access tokens.

Although you can work with org tokens in the web UI, you can also manage them with the org token API, which allows you to do the following:

  • Create a token
  • Retrieve one or more tokens using search criteria
  • Retrieve a token by specifying its name
  • Update a token specified by its name
  • Delete a token specified by its name
  • Update the secret for a token specified by its name
  • Set limits for requests that use a specific token

Authentication

To create, retrieve, update, or delete an org token, or to rotate the token secret, you need to authenticate with a session token that's associated with a SignalFx user that has administrative privileges.

For security reasons, SignalFx doesn't let you use an org token to authenticate a request to retrieve other tokens. To learn more, see the section Org token security in the API topics.

Org tokens and limits

If you're an Enterprise customer, you can set usage limits on an org token. Use this feature to apply the limits to data sources that are using that particular token.

For example, use org token limits to restrict the number of MTS you send using the /datapoint or /backfill endpoints, both of which require an org token for authentication.

Limit settings

For any org token you create, you can specify the following:

  • A limit or limits
  • A threshold for the limit. When the token's usage exceeds the threshold SignalFx issues a notification.
  • The notification for the threshold

If you don't specify limits, SignalFx applies the appropriate overage charges to MTS that exceed your subscription agreement.

If you don't specify a threshold, SignalFx doesn't send out a notification. When you reach the limit specified for the org token, SignalFx stops recording MTS, but keeps the MTS you've already sent.

You can turn on the threshold feature in the web UI, but you're restricted to a threshold of 90%.

If you set a threshold and a notification for it, but the notification has no recipients, SignalFx doesn't create a detector or send out the notification.

DPM limits

If your organization uses DPM pricing, you can set a DPM limit, threshold and notification for an org token. The limit restricts the number of MTS you can send with a /datapoint or /backfill request that uses the token.

This feature helps you control DPM costs for servers using a token that has limits. To learn more about token limits for DPM pricing, see the topic Track Organization DPM Usage with Access Tokens in the SignalFx product documentation.

Host-based pricing limits

If your organization uses host-based pricing, you can set limits,
thresholds, and a notification for an org token. Four different token limits are available:

  • Hosts: Limits the number of hosts that can use this token concurrently
  • Containers: Limits the number of Docker containers that can use this token concurrently
  • Custom metrics: Limits the number of custom metrics you send from your hosts
  • Hi-res metrics: Limits the number of high-resolution metrics you send from your hosts

To learn more about token limits for host-based pricing, see the topic Managing usage limits with access tokens in the SignalFx product documentation.

Usage-based pricing limits

Limits for usage-based pricing works the same as for host-based pricing, but you can only set limits, thresholds, and notifications for custom metrics and hi-res metrics.

Using Org token limits

Org tokens help you control spending you incur from your data sources.

For example, when you assign an org token to a test host and set low limits, you avoid using up your SignalFx quotas.

Another use of org token limits is to manage resource usage for different groups of users. When you have users in the U.S. and Canada sending data to SignalFx, you can assign them specific org tokens and manage the amount of data coming from each region.

Retrieve Tokens Using Query

Retrieve one or more org tokens specified by search criteria

Search for one or more org tokens by specifying all or part of the token name. If you've set token limits for the token, they're returned in the response body.

query Parameters
offset
integer <int32>

The object in the result set at which the API should start returning results to you. Each object contains the properties of an org access token.

limit
integer <int32>

The number of results to return from the result set. Regardless of the number you specify, SignalFx only returns a maximum of 1000 objects.

name
string

All or part of the org token name

header Parameters
X-SF-TOKEN
required
string

Authentication token. If you use an org token, SignalFx returns information only for the org token you use.

Responses

Response Schema: application/json
count
integer <int32>

Number of token objects that matched your query, also known as the result set. This isn't always the number of token objects in results. If you specify offset or limit or both, the number of objects you receive may be different from the value of count.

Array of objects (Properties of an org access token)

List of results, in the form of a JSON array

Response samples

Content type
application/json
{
  • "count": 0,
  • "results":
    [
    ]
}

Create Single Token

Create an org token

Creates an org token from the properties specified in the request body.

NOTE: You can't modify "read-only" properties. These properties are marked in the token model specification.

header Parameters
Content-Type
required
string

Format of the request body. Always application/json.

X-SF-TOKEN
required
string

Authentication token. Must be a session token (User API access token) associated with a SignalFx user that has administrative privileges.

Request Body schema: application/json

JSON object that specifies the properties of the new org token

description
string (Token description)

Extended description of the token. You assign this value when you create or update the token.

disabled
boolean (Token disabled flag)

Flag that controls enabling the token. If set to true, the token is disabled, and you can't use it for authentication.

Host-based limits and thresholds for an org token (object) or DPM limits and thresholds for an org token (object) or Usage-based limits and thresholds for an org token (object) (Limits associated with the org token)

Specifies org token limits and thresholds according to your pricing model. For DPM pricing, the object uses the dpmQuota field. For host-based pricing and usage-based pricing, the object uses the categoryQuota field.

You can only set limits if you have an Enterprise-level account.

name
string (Token name)

Token label. You assign this value when you create or update the token.

Array of Amazon EventBridge Threshold Notification (object) or BigPanda Threshold Notification (object) or (Jira Cloud or Jira Server Threshold Notification (object)) or Email Threshold Notification (object) or Microsoft Teams Threshold Notification (object) or Opsgenie Threshold Notification (object) or PagerDuty Threshold Notification (object) or ServiceNow Threshold Notification (object) or Slack Threshold Notification (object) or Team Email Threshold Notification (object) or SignalFx Team Threshold Notification (object) or VictorOps Threshold Notification (object) or Webhook URL Threshold Notification (object) or xMatters Threshold Notification (object)

Array of notification settings. Each element defines a notification that SignalFx sends when your organization is within 90% of exceeding an org token limit. You can specify more than one object, and each object can be of a different type.

To send email notifications:

  • For one or more individual users, use "type": "Email".
  • For a single SignalFx team, use "type": "TeamEmail".
  • For multiple SignalFx teams, use multiple array elements, each with "type": "TeamEmail" and the team ID.
  • To send emails to a team, the team must already exist.
    **NOTE:** "Team" sends notification messages using the team's notification policy, which may or may not send an email to team members. To learn more, see the description of the `"Team"` notification type.

Responses

Response Schema: application/json
created
integer <int64> (Token creation timestamp)

The token creation date and time, in Unix time
The system sets this value, and you can't modify it.

creator
string

SignalFx-assigned ID of the user that created this token.
The system sets this value, and you can't modify it.

description
string (Token description)

Extended description of the token. You assign this value when you create or update the token.

disabled
boolean (Token disabled flag)

Flag that controls enabling the token. If set to true, the token is disabled, and you can't use it for authentication.

expiry
integer <int64> (Token expiration timestamp)

Date and time that the token will expire, in Unix time
The system sets this value, and you can't modify it.

id
string (Token ID)

SignalFx-assigned token ID
The system sets this value, and you can't modify it.

lastUpdated
integer <int64>

The date and time that the token was last updated, in Unix time.
The system sets this value, and you can't modify it.

lastUpdatedBy
string

SignalFx-assigned ID of the user that last updated this token
The system sets this value, and you can't modify it.

latestRotation
integer <int64> (Timestamp of latest rotation)

Date and time when SignalFx last rotated the secret for this token, in Unix time.
The system sets this value, and you can't modify it.

Host-based limits and thresholds for an org token (object) or DPM limits and thresholds for an org token (object) or Usage-based limits and thresholds for an org token (object) (Limits associated with the org token)

Specifies org token limits and thresholds according to your pricing model. For DPM pricing, the object uses the dpmQuota field. For host-based pricing and usage-based pricing, the object uses the categoryQuota field.

You can only set limits if you have an Enterprise-level account.

name
string (Token name)

Token label. You assign this value when you create or update the token.

Array of Amazon EventBridge Threshold Notification (object) or BigPanda Threshold Notification (object) or (Jira Cloud or Jira Server Threshold Notification (object)) or Email Threshold Notification (object) or Microsoft Teams Threshold Notification (object) or Opsgenie Threshold Notification (object) or PagerDuty Threshold Notification (object) or ServiceNow Threshold Notification (object) or Slack Threshold Notification (object) or Team Email Threshold Notification (object) or SignalFx Team Threshold Notification (object) or VictorOps Threshold Notification (object) or Webhook URL Threshold Notification (object) or xMatters Threshold Notification (object)

Array of notification settings. Each element defines a notification that SignalFx sends when your organization is within 90% of exceeding an org token limit. You can specify more than one object, and each object can be of a different type.

To send email notifications:

  • For one or more individual users, use "type": "Email".
  • For a single SignalFx team, use "type": "TeamEmail".
  • For multiple SignalFx teams, use multiple array elements, each with "type": "TeamEmail" and the team ID.
  • To send emails to a team, the team must already exist.
    **NOTE:** "Team" sends notification messages using the team's notification policy, which may or may not send an email to team members. To learn more, see the description of the `"Team"` notification type.
secret
string (Current authentication secret for the token)

Authentication secret key that protects the org token
The system sets this value, and you can't modify it.

Response Schema: application/json
code
integer (Error code)

HTTP response code for the error

message
string (Error message)

Cause of the error, any one of:

  • "Please provide a name for this token."
  • "Unable to create or update the given token. Please try again later."
  • "A token with the same name already exists!"
  • "Category quota cannot be set on a DPM subscription plan"
  • "DPM quota cannot be set on a Hosts subscription plan"
  • "Host/Container quota cannot be set on a MTS subscription plan"

Request samples

Content type
application/json
{
  • "description": "string",
  • "disabled": true,
  • "limits":
    {
    },
  • "name": "string",
  • "notifications":
    [
    ]
}

Response samples

Content type
application/json
{
  • "created": 1556746230000,
  • "creator": "string",
  • "description": "string",
  • "disabled": true,
  • "expiry": 1558474230000,
  • "id": "string",
  • "lastUpdated": 1557696630000,
  • "lastUpdatedBy": "string",
  • "latestRotation": 1556832630000,
  • "limits":
    {
    },
  • "name": "string",
  • "notifications":
    [
    ],
  • "secret": "string"
}

Delete Single Token

Deletes the org token specified in the {name} path parameter

Deletes the org token you specify in the name path parameter

path Parameters
name
required
string

Name of the org token you want to delete

header Parameters
X-SF-TOKEN
required
string

Authentication token. Must be a session token (User API access token) associated with a SignalFx user that has administrative privileges.

Responses

Retrieve Token Using Name

Retrieve the org token specified in the {name} path parameter

Retrieves an existing org token based on the name you specify in the name path parameter

path Parameters
name
required
string

Name of the org token you want to retrieve

header Parameters
X-SF-TOKEN
required
string

Authentication token. If you use an org token, SignalFx returns information only for the org token you use.

Responses

Response Schema: application/json
created
integer <int64> (Token creation timestamp)

The token creation date and time, in Unix time
The system sets this value, and you can't modify it.

creator
string

SignalFx-assigned ID of the user that created this token.
The system sets this value, and you can't modify it.

description
string (Token description)

Extended description of the token. You assign this value when you create or update the token.

disabled
boolean (Token disabled flag)

Flag that controls enabling the token. If set to true, the token is disabled, and you can't use it for authentication.

expiry
integer <int64> (Token expiration timestamp)

Date and time that the token will expire, in Unix time
The system sets this value, and you can't modify it.

id
string (Token ID) <