Setting up an authorization to Web Connect

This guide explains how to set up an authorization to Web Connect.

Introduction

Web Connect is a universal connector in Adverity. With Web Connect, you can set up a connection to a data source API that does not have an available connector. For more information, see Collecting data using Web Connect.

When you connect to an API using Web Connect you may need to create an authorization.

Depending on the API requirements, you may need to enter your authentication credentials in the request URL, header or body instead of creating an authorization in Adverity. In this case, select Continue without authorization in the Authorization step of the datastream wizard.

The list below explains the available authorization types for Web Connect and when each authorization type should be used.

|Web Connect| (Basic authentication)

Use for APIs that use username and password authorization.

|Web Connect| (Bearer authentication)

Use for APIs that use a bearer token retrieved from the data source API to authorize the requests.

|Web Connect| (Static bearer token)

Use for APIs that use a bearer token without an expiration date generated by the data source application.

|Web Connect| (Cookie session)

Use for APIs that use a unique user identifier known as a cookie session. The identifier is generated when Adverity connects to the data source with the user credentials.

|Web Connect| (Custom headers)

Use for APIs that use custom authorization keys in the request header.

|Web Connect| (OAuth)

Use for APIs that use the OAuth (Open Authorization) protocol.

|Web Connect| (OAuth 2)

Use for APIs that use the OAuth 2.0 (Open Authorization 2.0) protocol.

Setting up a Web Connect (Basic authentication) authorization

With the basic authentication, Adverity uses a username and password to authorize the requests to the data source API.

To set up a basic authorization to Web Connect, fill in the following fields:

Username

Enter the username to be used to authorize the API requests.

Password

Enter the password to be used to authorize the API requests.

Setting up a Web Connect (Bearer authentication) authorization

With the bearer authentication, Adverity uses a bearer token to authorize the requests to the data source API. The token is retrieved from the data source API upon an authorization request (unlike the static bearer token). The bearer token may expire and need to be retrieved again through the API. When using this authorization type, Adverity retrieves and uses the token automatically based on your configuration.

To set up a bearer token authorization to Web Connect, you need to complete two steps:

1. Retrieving a bearer token from the API

2. Using the bearer token to authorize the API requests

Retrieving a bearer token from the API

To retrieve a bearer token from the API, fill in the following fields:

Authorization URL

Enter the URL of the API endpoint to retrieve the bearer token from.

Method

Select the method for the authorization request.

Content type

Select the encoding type of the authorization request body.

Note

Most APIs use the application/json content type, but make sure to select the type supported by your data source API.

Body

Enter the body of the authorization request in the JSON format. The body should contain all necessary information for the API to issue a bearer token.

For example, your authorization request body may look like this:

{
   "grant_type": "client_credentials",
   "client_id": "{your_client_id}",
   "client_secret": "{your_client_secret}"
}

Access token path

(Optional) Enter a JSONPath to extract the bearer token from the JSON response from the authorization URL.

For example, if the token is returned as a value of the API_token field, enter API_token.

If this field is left empty, Adverity tries to extract the token automatically.

Using the bearer token to authorize API requests

To use the bearer token to authorize the API requests, fill in the following fields:

Note

You can configure how to use the bearer token in one of the following ways:

• Specifying a full header including the bearer token in the Headers field below

• Providing a key-value pair for the authorization header in the Header key and Header value fields below

• Leaving these fields empty and using the retrieved bearer token in the Web Connect datastream configuration with the {YOUR_TOKEN} placeholder

Headers

Enter the request headers to be used to authorize the API requests in JSON format.

To include the retrieved token in a header, use the {YOUR_TOKEN} placeholder.

Header key

Enter the key of the authorization header to be used to authorize the API requests.

Header value

Enter the value of the authorization parameter in the header when making an API request.

To include the retrieved token in the header, use the {YOUR_TOKEN} placeholder.

Setting up a Web Connect (Static bearer token) authorization

With the static bearer token authentication, Adverity uses a static bearer token to authorize the requests to the data source API. The static bearer token does not have an expiration date and is granted to the user through the data source application.

Note

To authorize the API requests, the token will be used in the Authorization header with the value Token, for example,

Authorization: Token {YOUR_TOKEN}

To specify how to use this token to authorize the API requests, use the {YOUR_TOKEN} placeholder in the Web Connect datastream configuration.

Prerequisites

• Obtain a static bearer token from the data source application or by contacting the data source customer support.

Configuration

To set up a static bearer token authorization to Web Connect, fill in the following fields:

Static bearer token

Enter the static token to be used to authorize the API requests.

Setting up a Web Connect (Cookie session) authorization

With the cookie session authorization, Adverity uses a cookie session token to authorize the requests to the data source API. The cookie session token is retrieved from the data source API upon request based on the user credentials and optionally other parameters. The cookie session token may need to be refreshed. When using this authorization type, Adverity retrieves and updates the token automatically according to the specified configuration.

Note

To authorize the API requests, the cookie session token will be used in the cookie header, for example cookie: example.cookie=ABC. Both the cookie token name and value will be retrieved by Adverity from the data source API.

To set up a cookie session authorization to Web Connect, fill in the following fields:

Username

Enter the username to be used to generate the cookie session token.

Password

Enter the password to be used to generate the cookie session token.

Authorization URL

Enter the URL of the API endpoint to retrieve the cookie session token from.

Headers

(Optional) Enter the headers of the authorization request in the JSON format.

Login form fields

Login form fields are the additional fields in the login form that need to be sent to the API for successful authentication. These fields often include hidden values or tokens required by the API for security purposes, such as CSRF tokens or session IDs.

To use the additional login form fields, enter a list of their CSS selectors.

For example, if the login form includes a hidden field my_hidden_field, specify it using the CSS selector in the following way: ["input[name='my_hidden_field']"].

Setting up a Web Connect (Custom headers) authorization

With the custom headers authentication, Adverity uses the custom headers you provide to authorize the requests to the data source API. You can include any type of authorization key that should be used in the request header, for example, providing the client ID or a combination of tokens.

Prerequisites

• Obtain an API token or other type of credentials to be used in the headers from the data source application.

Configuration

To set up a custom headers authorization to Web Connect, fill in the following fields:

Headers

Enter the request headers to be used to authorize the API requests in JSON format.

For example, to authorize the requests using the X-Api-Token header with the value 123, enter the following expression:

{
   "X-Api-Token": "123"
}

Setting up a Web Connect (OAuth) authorization

With the OAuth authentication, Adverity uses an access token to authorize the requests to the data source API. The access token is retrieved from the data source API using the OAuth 1.0 protocol.

Note

To specify how to use the access token to authorize the API requests, use the {YOUR_TOKEN} placeholder in the Web Connect datastream configuration.

To set up an OAuth authorization to Web Connect, fill in the following fields:

Access token URL

Enter the URL of the API endpoint to retrieve the access token from.

Payload format

Select the format in which to send the authorization request.

Authorization request parameters

(Optional) Enter the parameters for the authorization request in the selected format.

Grant type

Select the authentication method to be used to grant access to the data source.

Client ID and Client secret

For the Client credentials grant type, enter your client ID and secret.

Username and Password

For the Password grant type, enter your username and password.

Setting up a Web Connect (OAuth 2) authorization

With the OAuth 2 authentication, Adverity uses an access token to authorize the requests to the data source API. The access token is retrieved from the data source API using the OAuth 2.0 protocol.

To set up an OAuth 2 authorization to Web Connect, fill in the following fields:

Client ID

Enter the client ID to be used to retrieve an authorization code.

Client secret

Enter the client secret to be used to retrieve an authorization code.

Authorization code URL

Enter the URL of the API endpoint to retrieve the authorization code from.

Authorization page parameters

(Optional) Enter the parameters for the authorization code request in the JSON format.

Access token URL

Enter the URL of the API endpoint to retrieve the access token from.

Token placement

Select the placement of the access token when using it to authorize the API requests.

What’s next?

Once you’ve created an authorization to Web Connect, set up a Web Connect datastream. For more information, see Collecting data using Web Connect.