ThousandEyes API v6
ThousandEyes API v6

Authentication

ThousandEyes API v6 has been deprecated as of May 27, 2024. We strongly recommend that you migrate to ThousandEyes API v7 to ensure continued support and access to new features. For more information, see the deprecation notice.

Two authentication mechanisms are available for ThousandEyes API v6:

  • Basic authentication
  • OAuth2 bearer token

Your API tokens for both mechanisms can be managed in Account Settings > Users and Roles > Profile.

Obtaining your API Token

In order to interact with the ThousandEyes API, you must first obtain an API 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.

Basic Authentication

Basic authentication is not available in the EU region. In the EU region, you must use OAuth2 bearer token authentication.

Basic authentication allows you to authenticate to the ThousandEyes API with a unique token associated with your user account. To authenticate with a basic authentication token, you must include your credentials in a request header. The header name must be Authorization and the value must be Basic <credentials>, where <credentials> is the Base64 encoding of your ThousandEyes email address and your basic authentication token, joined by a colon.

For example, if your ThousandEyes e-mail address is user@example.com, and your basic authentication token is b3pxka6wgv81zghx, then <credentials> is the Base64 encoding of user@example.com:b3pxka6wgv81zghx, and your HTTP requests must contain the following header:

Code Snippet
CopyAuthorization: Basic dXNlckBleGFtcGxlLmNvbTpiM3B4a2E2d2d2ODF6Z2h4

Also, using curl, for example, you can pass in your credentials with the -u argument, and it automatically includes the Authorization: Basic ... header in the request.

curl
Copycurl https://api.thousandeyes.com/v6/status.json \
  -u user@example.com:b3pxka6wgv81zghx

To authenticate in Postman using basic authentication:

  1. In the Authorization tab, select the Basic Auth type.
  2. In the Username field, enter your ThousandEyes e-mail address.
  3. In the Password field, enter your basic authentication token.

Most HTTP clients provide a way to specify basic authentication credentials and perform the Base64 encoding.

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
Copycurl https://api.thousandeyes.com/v6/status.json \
  --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 base64 encoding the email:authtoken and setting an Authorization header. The following example takes two inputs and sets the required headers to work with the ThousandEyes API using basic authentication:

Code Snippet
Copy[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$apiuser       = "{email}"
$apipassword   = "{authToken}"
$authorization = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($apiuser + ":" + $apipassword))
$headers       = @{"accept"= "application/json"; "content-type"= "application/json"; "authorization"= "Basic " + $authorization}
$response      = Invoke-WebRequest https://api.thousandeyes.com/v6/agents.json -Headers $headers
$response.content

When leveraging the bearer token, the token itself can be passed directly as a string:

Code Snippet
Copy[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.json -Headers $headers
$response.content

Note: Both the Basic Authentication Token and the OAuth2 Bearer Token are available from your account settings page under the "Profile" tab, in the "User API Tokens" section.

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.

Next