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, 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.
To retrieve an org token, you can use an org token or session token. The session token doesn't have to be associated with a user that has administrative privileges.

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

get /token

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/token

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
Content-Type
required
string

Format of the request payload. The only allowed value is 'application/json'

X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of one or more org tokens

Response Schema: application/json
count
integer <int32>

Number of token objects in the result set. This value is the number of token objects that matched your query. However, if you specify the offset or limit query parameters, or both, the number of objects you receive in the response body may be different from the value of count.

results
Array of objects (Properties of an org access token)

Array of token objects.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "results":
    [
    ]
}

Create Single Token

Create an org token

post /token

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/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 payload. The only allowed value is '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)

An extended description of 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.

limits
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. Use the form that corresponds to your pricing model:

  • For DPM pricing, use "dpmQuota"
  • For host-based pricing, use "categoryQuota"

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

name
required
string (Token name)

A label ( a name ) you assign to the token

notifications
array

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 one or more entire SignalFx teams, use "type": "TeamEmail"
  • For one or more members of a single team, use "type": "Team"
  • For one or more members of multiple teams, use "type": "TeamEmail"
  • To send emails to a team, the team must already exist.
  • To send email to specific members of a team, the team must already exist, and you must specify the team members who will receive emails.

Responses

200

Successful creation of an org token

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

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

creator
string

SignalFx-assigned ID of the user that created this token

description
string (Token description)

An extended description of 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 UTC-relative. 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 UTC-relative. The system sets this value, and you can't modify it.

lastUpdatedBy
string

SignalFx-assigned ID of the user that last updated this token

latestRotation
integer <int64> (Timestamp of latest rotation)

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

limits
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. Use the form that corresponds to your pricing model:

  • For DPM pricing, use "dpmQuota"
  • For host-based pricing, use "categoryQuota"

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

name
required
string (Token name)

A label ( a name ) you assign to the token

notifications
array

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 one or more entire SignalFx teams, use "type": "TeamEmail"
  • For one or more members of a single team, use "type": "Team"
  • For one or more members of multiple teams, use "type": "TeamEmail"
  • To send emails to a team, the team must already exist.
  • To send email to specific members of a team, the team must already exist, and you must specify the team members who will receive emails.
secret
string (Current authentication secret for the token)

Authentication secret key that protects the org token

400

Request failed because the request body is invalid. This happens when:

  • You don't provide a token name. The message in the body is:
    "Please provide a name for this token."
  • An internal error occurs, and SignalFx can't create the token. The message in the body is:
    "Unable to create or update the given token. Please try again later."
  • You try to create a token that already exists, The message in the body is:
    "A token with the same name already exists!"
  • Your organization uses host-based pricing, but you tried to set the DPM limit. The message in the body is
    "DPM quota cannot be set on a Hosts subscription plan."
  • Your organization uses DPM pricing, but you tried to set a host-based limit. The message in the body is
    "Category quota cannot be set on a DPM subscription plan."
  • Your organization uses custom metric-based pricing, but you tried to set a host or container limit. The message in the body is "Host/Container quota cannot be set on a MTS subscription plan".
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

application/json
Copy
Expand all Collapse all
{
  • "description": "string",
  • "disabled": true,
  • "limits":
    {
    },
  • "name": "string",
  • "notifications":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556746230000,
  • "creator": "string",
  • "description": "string",
  • "disabled": true,
  • "expiry": 1558474230000,
  • "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

delete /token/{name}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/token/{name}

Deletes the org token you specify in the name path parameter.

path Parameters
name
required
string

The name of the org token you want to delete

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is '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.

Responses

200

Successful deletion of the org token

Retrieve Token Using Name

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

get /token/{name}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/token/{name}

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

path Parameters
name
required
string

The name of the org token you want to retrieve

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is 'application/json'

X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of the specified org token

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

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

creator
string

SignalFx-assigned ID of the user that created this token

description
string (Token description)

An extended description of 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 UTC-relative. 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 UTC-relative. The system sets this value, and you can't modify it.

lastUpdatedBy
string

SignalFx-assigned ID of the user that last updated this token

latestRotation
integer <int64> (Timestamp of latest rotation)

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

limits
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. Use the form that corresponds to your pricing model:

  • For DPM pricing, use "dpmQuota"
  • For host-based pricing, use "categoryQuota"

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

name
required
string (Token name)

A label ( a name ) you assign to the token

notifications
array

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 one or more entire SignalFx teams, use "type": "TeamEmail"
  • For one or more members of a single team, use "type": "Team"
  • For one or more members of multiple teams, use "type": "TeamEmail"
  • To send emails to a team, the team must already exist.
  • To send email to specific members of a team, the team must already exist, and you must specify the team members who will receive emails.
secret
string (Current authentication secret for the token)

Authentication secret key that protects the org token

Response samples

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

Update Single Token

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

put /token/{name}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/token/{name}

Updates properties of an org token you specify in the name path parameter.
NOTE: You can't modify "read-only" properties. These properties are marked in the token model specification.

path Parameters
name
required
string

The name of the org token you want to update

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is '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 you want to update

description
string (Token description)

An extended description of 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.

limits
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. Use the form that corresponds to your pricing model:

  • For DPM pricing, use "dpmQuota"
  • For host-based pricing, use "categoryQuota"

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

name
required
string (Token name)

A label ( a name ) you assign to the token

notifications
array

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 one or more entire SignalFx teams, use "type": "TeamEmail"
  • For one or more members of a single team, use "type": "Team"
  • For one or more members of multiple teams, use "type": "TeamEmail"
  • To send emails to a team, the team must already exist.
  • To send email to specific members of a team, the team must already exist, and you must specify the team members who will receive emails.

Responses

200

Successful update of the org token

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

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

creator
string

SignalFx-assigned ID of the user that created this token

description
string (Token description)

An extended description of 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 UTC-relative. 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 UTC-relative. The system sets this value, and you can't modify it.

lastUpdatedBy
string

SignalFx-assigned ID of the user that last updated this token

latestRotation
integer <int64> (Timestamp of latest rotation)

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

limits
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. Use the form that corresponds to your pricing model:

  • For DPM pricing, use "dpmQuota"
  • For host-based pricing, use "categoryQuota"

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

name
required
string (Token name)

A label ( a name ) you assign to the token

notifications
array

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 one or more entire SignalFx teams, use "type": "TeamEmail"
  • For one or more members of a single team, use "type": "Team"
  • For one or more members of multiple teams, use "type": "TeamEmail"
  • To send emails to a team, the team must already exist.
  • To send email to specific members of a team, the team must already exist, and you must specify the team members who will receive emails.
secret
string (Current authentication secret for the token)

Authentication secret key that protects the org token

400

Request failed because the request body is invalid. This happens when:

  • You don't provide a token name. The message in the body is:
    "Please provide a name for this token."
  • An internal error occurs, and SignalFx can't create the token. The message in the body is:
    "Unable to create or update the given token. Please try again later."
  • You try to create a token that already exists, The message in the body is:
    "A token with the same name already exists!"
  • Your organization uses host-based pricing, but you tried to set the DPM limit. The message in the body is
    "DPM quota cannot be set on a Hosts subscription plan."
  • Your organization uses DPM pricing, but you tried to set a host-based limit. The message in the body is
    "Category quota cannot be set on a DPM subscription plan."
  • Your organization uses custom metric-based pricing, but you tried to set a host or container limit. The message in the body is "Host/Container quota cannot be set on a MTS subscription plan".
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

application/json
Copy
Expand all Collapse all
{
  • "description": "string",
  • "disabled": true,
  • "limits":
    {
    },
  • "name": "string",
  • "notifications":
    [
    ]
}

Response samples

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

Rotate Token Secret

Rotates the secret for the org token specified in the {name} path parameter

post /token/{name}/rotate

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/token/{name}/rotate

Generates a new token secret for the token specified by the name path parameter, and deauthorizes the previous token secret.

path Parameters
name
required
string

The name of the org token you want to update with a new secret

query Parameters
graceful
integer <int32>

Specifies a grace period to wait before updating the secret, in seconds

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is '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.

Responses

200

Successful rotation of the token secret

© Copyright 2019 SignalFx.

Third-party license information