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.

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.

Because you don’t have to update them regularly, org tokens are best used in in scenarios where you want to avoid updating a running program. In addition, when programs send data points to SignalFx using the API, the send request must use an org token.

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.

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 tokens

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

Session tokens from a SignalFx administrator

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 authentication token to retrieve org tokens.

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