Authentication

ThousandEyes v7 APIs uses the OAuth2 bearer token authentication mechanism. Your bearer token can be managed in 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 Account Settings > Users and Roles > Profile > User API Tokens.

Note: Tokens are only displayed when you create or regenerate them. Ensure that you safely store your token (for example, in a password manager), as you will not be able to view the token again in the ThousandEyes platform after generating it. If you lose or forget your token, you can regenerate a new token in the ThousandEyes dashboard.

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.