Many APIs require that the caller specifies authentication information. The API determines which type of authentication must be used. This articles discusses which types of authentication are possible in Uptrends.

Default authentication types

The Authentication section on the Request tab of a Multi-step API monitor offers several authentication types. They all use a username / password combination, but the way those credentials are processed and sent to the API is different for each type:

  • Basic Authentication: the username and password are encoded in a simple Base-64 encoded format and sent to the API server.
  • NTLM (Windows) Authentication: when you specify this type, several requests are sent to the API to negotiate about the authentication that should be used, before the final HTTP request is sent with the appropriate authentication. This sequence of requests counts as one single step. If a Windows domain must be specified, include it in the username: YOURDOMAIN\username
  • Digest Authentication: when you specify this type, we'll send two consecutive requests to the API. The first request sends a request without any authentication information, and expects the server to return authentication-specific instructions in the WWW-Authenticate response header. The username and password are hashed according to these instructions (including nonce and qop values) and sent across in the second request which is then properly authenticated. This sequence of requests counts as one single step.
  • None: choose None if you don't want to use authentication for your HTTP request.

HTTP headers

When you use any of these authentication types, you don't need to specify any other authentication-specific HTTP headers: we will generate the appropriate Authorization header for you.

Variable support

The username and password fields support variables. You can create predefined variables (for example: {{username}} and {{password}}) with the appropriate values and then use those variable names in the authentication fields. More information about variables and predefined variables.

Custom authentication (including OAuth)

When your API uses OAuth as its authentication protocol, you'll need a more elaborate setup. Depending on your API, you may need something quite specific to your situation. OAuth 2.0 in particular uses at least one separate request just for the authentication process. This request requests access to the API (using one of the default authentication types, by specifying login credentials in the URL, or even performing a web page login). Upon successful authentication, the OAuth access token is captured and stored in a variable, so it can be used in subsequent requests.

If you're not using OAuth but a different protocol, it may still operate in a similar way: you'll first have to specify login information that "proves" your identity to the API. The API server will then respond by giving you a login token that is valid for a certain amount of time. By capturing that token and storing it in a variable, you can execute a sequence of requests that use the login token to gain access.

Setting up OAuth 2.0 authentication

In the following example, we'll set up a simple form of OAuth 2.0 authentication. Our goal is to acquire an access token from the API, which we can then use in later requests.

To do this, we will first send a request containing the appropriate OAuth fields. In this case, we're requesting access based on an authorization code, a client id and a client secret. The client id and client secret are fixed values that we can define as predefined variables. In our simple setup, the authorization code will also be a fixed value, but in your setup it may be necessary to retrieve that authorization code first using a separate step.

First, we'll add those values to the predefined variables:

With those variables defined, we can now set up a request to our API by including references to those variables, along with any other parameters the API expects. In the first step of our multi-step setup, add this URL:


We expect the API to return a data structure that contains the access token we need, but how will that data structure be formatted? To ensure we will get JSON-formatted data, let's tell the server we will only accept the application/json format by specifying that in an HTTP header:

With this header specified, we can now expect the response to look something like:


All we need to do now, is capture the access_token field in the JSON response. To do this, we'll create a new variable in the Response tab of our step:

  • The response should contain JSON, so choose Response body as JSON as the source for our variable.
  • Since the access_token attribute is located at the top level in our data structure, our JSON expression is simply access_token.
  • We'll choose accesstoken as our variable name. This is the name we'll refer to in later steps.

Even though the main goal of this first step is to capture the access token, it already performs some monitoring as well: if the API returns an error at this point, or if the response does not contain an access token, this step will detect this and report an error.

Now that we have a valid access token, we can finally access the actual API method we want to check (say, for retrieving a list of products). Create a new step to define this API call. After specifying the method and URL for this new request, we're going to pass in the access token we've just captured. OAuth 2.0 based APIs expect an HTTP header called Authorization, with a value Bearer {{accesstoken}}

We can repeat this for each additional step that requires the same access token.