Authentication

ThousandEyes v7 APIs use the HTTP bearer authentication scheme. You can authenticate with an API Key or an OAuth bearer token.

Choosing an API Credential

Use an API Key for production integrations and automation. API Keys belong to your organization, can have their own permissions, and are not tied to an individual user account.

Use an OAuth bearer token for testing, exploration, and ad hoc requests. OAuth bearer tokens use the permissions assigned to the user who owns the token.

Note: The full value of an API Key or OAuth bearer token is shown only when ThousandEyes generates and displays a new value. Store the credential securely, such as in a password manager. You cannot view the same credential value again in the ThousandEyes platform.

API Keys

Create and manage API Keys in Manage > Account Settings > Users and Roles > API Keys.

Your user role must have the Manage own API Keys permission or the Manage all API Keys in organization permission.

For more information, see API Keys.

You cannot create an API Key with the API. The API supports only API Key regeneration. To regenerate an API Key with the API, call the Regenerate API Key operation and authenticate with the API Key that you want to regenerate. OAuth bearer tokens and other API Keys cannot regenerate that key through this endpoint.

OAuth Bearer Tokens

To create or manage an OAuth bearer token, go to Manage > Account Settings > Users and Roles > Profile. Under User API Tokens, create or manage the OAuth Bearer Token.

For more information, see User API Tokens.

Replace an OAuth Bearer Token

If you lose an OAuth bearer token or need to rotate it, you can replace it in one of two ways:

Using the UI

  1. Revoke the existing OAuth Bearer Token.
  2. Create a new OAuth Bearer Token.
  3. Update your applications to use the new token.

Using the API
Call the Regenerate API token operation before the current OAuth bearer token expires. After regeneration, the previous token remains valid for 14 days, or until its scheduled expiration date, whichever comes first.

Note: The Regenerate action in the ThousandEyes platform applies only to the Basic Authentication Token. For OAuth bearer tokens, use the revoke-and-create flow in the UI, or the regenerate API if the current token is still valid.

Sending the Authorization Header

To authenticate with an API Key or OAuth bearer token, include it in the Authorization header of your requests. The value of the header must be Bearer <your-api-credential-here>.

The following example shows bearer authentication with curl:

curl https://api.thousandeyes.com/v7/tests \
  --header "Authorization: Bearer $BEARER_TOKEN"

To authenticate in Postman with an API credential:

  1. In the Authorization tab, select the Bearer token type.
  2. In the Token field, enter your API credential.

PowerShell Syntax

You can use your API credential with the API in Windows PowerShell by setting the Authorization header. Pass the credential value directly as a string:

$apiCredential = "{apiCredential}"
$headers  = @{"accept"= "application/json"; "content-type"= "application/json"; "authorization"= "Bearer " + $apiCredential}
$response = Invoke-WebRequest https://api.thousandeyes.com/v7/tests -Headers $headers
$response.content

Scopes and Roles

Each API reference section provides details on the necessary scopes and roles for access. For detailed information on all scopes and roles, refer to the Reference Documentation.

Account Lockout

Your account could be locked because of a number of failed authentication attempts into the ThousandEyes platform.

If attempts to reach the API return a 401 UNAUTHORIZED response code, but your credentials are correct, your account might be locked. Try logging in to the ThousandEyes platform. If your account is locked, you must reset your password.

Source IP block

When 120 or more unauthorized requests (resulting in the 401 UNAUTHORIZED response) are issued from a given source IP address within an hour, API server will start responding with the 429 TOO MANY REQUESTS response code. Your API script should handle 401 UNAUTHORIZED error and prevent further requests to avoid the source IP block.

For error responses, see the response status codes documentation.