Authentication

ThousandEyes v7 APIs uses the OAuth2 bearer token authentication mechanism. Your bearer token can be managed in Manage > Account Settings > Users and Roles > Profile.

Obtaining your Bearer Token

In order to interact with the ThousandEyes API, you must first obtain a bearer token.

  1. Open your ThousandEyes dashboard.
  2. Once logged in, navigate to Manage > Account Settings > Users and Roles > Profile > User API Tokens.

Note: Tokens are only displayed when you create or regenerate them. Store the token securely (for example, in a password manager). You cannot view a bearer token again in the ThousandEyes platform after creation.

Replace a Bearer Token

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

Using the UI

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

Using the API
Call the Regenerate API token operation before the current 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 dashboard applies only to Basic Authentication tokens. For bearer tokens, use the revoke-and-create flow in the UI, or the regenerate API if the current token is still valid.

OAuth2 Bearer Token

The OAuth2 bearer token allows you to authenticate to the ThousandEyes API using a token, without providing a username. To authenticate with your OAuth2 bearer token, you must include it in the Authorization header of your requests. The value of the header must be Bearer <your-oauth-bearer-token-here>.

The following example shows OAuth2 bearer token authentication with curl: 

curl https://api.thousandeyes.com/v7/tests \
  --header "Authorization: Bearer f537f4ac-2921-3199-bbab-d5a43f1c2b60"

To authenticate in Postman with an OAuth2 bearer token:

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

Powershell Syntax

You can create and use your credentials with the API in Windows Powershell. This is possible by setting an Authorization header. When leveraging the bearer token, the token itself can be passed directly as a string:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$apitoken = "{bearerToken}"
$headers  = @{"accept"= "application/json"; "content-type"= "application/json"; "authorization"= "Bearer " + $apitoken}
$response = Invoke-WebRequest https://api.thousandeyes.com/{{ site.version_url_prefix_request }}/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 up due to a number of failed authentication attempts into the ThousandEyes application.

If attempts to reach the API are returning an 401 UNAUTHORIZED response code, but your credentials are correct, it is possible that your account is locked up. Try logging into the App, if your account is locked up, you will be required to 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.