SignalFx Developers Guide

Authentication Tokens

The SignalFx API does authentication based on tokens you send in the X-SF-TOKEN REST request header parameter. SignalFx generates these tokens as randomized strings. You can obtain tokens using the web UI or the API.

Types of authentication tokens

SignalFx has two types of authentication tokens:

Org tokens

Known as Access Tokens in the SignalFx web UI, org tokens are long-lived organization-level tokens. By default, org tokens persist for 5 years, but the administrator for your SignalFx organization can disable them at any point.

You must use an org token when you send data points to SignalFx using the API. To learn more, see Org token requirements.

SignalFx restricts the use of org tokens for authentication. To learn more, see Org token security.

Session tokens

Known as User API Access Tokens in the SignalFx web UI, session tokens are short-lived user-level tokens. Session tokens automatically expire after 30 days, but you can immediately create a new one. You can create create a session token on your Profile page in the SignalFx web UI or by calling the operation POST /session.

Some API operations require a session token associated with a user who has administrative privileges (a SignalFx administrator). You can’t use an org token with these operations.

The rest of this topic describes the type of token needed for each operation.

Topics in the REST API reference also describe the specific token type needed for their methods and endpoints.

Org token security

For security reasons, SignalFx doesn’t let you use an org token to authenticate a request to retrieve other tokens. This feature protects your set of org tokens in case one of them becomes compromised. For example, if one of your org tokens is accidentally exposed, an attacker can’t use it to list your other tokens.

If someone person uses an org token in a retrieve request, SignalFx only returns the information for that token.

This limitation doesn’t apply to session tokens.

Token requirements

You can authenticate an API operation with either an org token or a session token, except for the operations listed in this section.

Org token requirements

These API operations require an org token:

  • POST https://ingest.{REALM}.signalfx.com/v2/datapoint

  • POST https://ingest.{REALM}.signalfx.com/v2/backfill

  • POST https://ingest.{REALM}.signalfx.com/v2/event

  • POST https://ingest.{REALM}.signalfx.com/v1/trace

SignalFx restricts the use of org tokens for authentication. To learn more, see Org token security.

SignalFx administrator session token requirements

Some API operations require a session token obtained by a user who is a SignalFx administrator. The followed table summarizes the operations.

The following table lists the affected operations.

Table 1. Operations that require a session token from a SignalFx administrator
API Task Operation

Dashboard groups

Change or remove write permissions for a user other than yourself

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}
with a request body that contains an update to to the list of users or teams in authorizedWriters, when your user ID isn’t already in authorizedWriters.

Dashboards

Change or remove write permissions for a user other than yourself

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}
with a request body that contains an update to authorizedWriters, when you’re not already in authorizedWriters.

Detectors

Change or remove write permissions for a user other than yourself

PUT https://api.{REALM}.signalfx.com/v2/detector/{id}
with a request body that contains an update to the list of users or teams in authorizedWriters, when your user ID isn’t already in authorizedWriters.

Integrations

Create an integration

POST https://api.{REALM}.signalfx.com/v2/integration

Update a single integration

PUT https://api.{REALM}.signalfx.com/v2/integration/{id}

Delete a single integration

DELETE https://api.{REALM}.signalfx.com/v2/integration/{id}

Validate an integration

GET https://api.{REALM}.signalfx.com/v2/integration/validate/{id}

Org tokens

Create an org token

POST https://api.{REALM}.signalfx.com/v2/token

Update a single org token

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

Delete a single org token

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

Rotate the org token secret

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

Organizations

Get the organization object for the organization

GET https://api.{REALM}.signalfx.com/v2/organization

Retrieve one or more member objects for the organization

GET https://api.{REALM}.signalfx.com/v2/organization/member

Create, update, or delete a custom category

PATCH https://api.{REALM}.signalfx.com/v2/organization/custom-categories

Invite a member to the organization

POST https://api.{REALM}.signalfx.com/v2/organization/member

Invite one or more members to the organization

POST https://api.{REALM}.signalfx.com/v2/organization/members

Grant administrative access to a member

PUT https://api.{REALM}.signalfx.com/v2/organization/member/{id}

Delete a member from the organization

DELETE https://api.{REALM}.signalfx.com/v2/organization/member/{id}

Teams

Create a team

POST https://api.{REALM}.signalfx.com/v2/team

Update information about a team

PUT https://api.{REALM}.signalfx.com/v2/team/{id}

Add or remove a team member other than yourself.

PUT https://api.{REALM}.signalfx.com/v2/team/{id}/members
with a request body that adds your user ID to members or removes it from members.

Delete a team

DELETE https://api.{REALM}.signalfx.com/v2/team/{id}

Obtaining tokens

Both the web UI and the API let you manage tokens.

Web UI

To get the org token for your organization, go to the Organization Overview in the SignalFx web UI and click the Access Tokens option. SignalFx administrators can also get a new token or manage organization tokens from this location.

To get a session token, go to your profile page to generate a User API Access Token.

API

Org tokens

Using the API to create, update, or delete an org token requires a session token associated with a SignalFx administrator. Refer to the table in the previous section for more information.

You can use any type of session token to retrieve org tokens, but you can’t use an org token. For more information, see Org token security.

Session tokens

To create a session token, use the operation POST https://api.{REALM}.signalfx.com/v2/session. You don’t need a token to create a session token; instead, you specify the email and password of an organization user in the operation’s request body.

Use the operation DELETE https://api.{REALM}.signalfx.com/v2/session to delete a session token. Specify the token you want to delete in the X-SF-TOKEN header parameter.

© Copyright 2019 SignalFx.

Third-party license information