Connection Strings: HTTP/S
This section provides an overview of various configuration settings available with DataZen to authenticate with HTTP/S services, such as cloud platforms, social media endpoints, or other Web APIs.
No Authentication
Enter the service URI to call. Although this is generally also the service endpoint, certain HTTP/S endpoints have a different URI for authentication. This URI should be the one used to authenticate.
This screenshot shows you how to configure an HTTP/S endpoint that does not require authentication.
Avoiding a trailing '/' at the end of the URI can make it easier to configure HTTP / REST calls on other screens.
See the Rate Limiting section for information on how to control the frequency of HTTP/S calls.
API Key Authentication
For HTTP/S Services that require an authentication key, choose API Key for the authentication mode. This setting requires two values: the key name and its value (the secret).
By default, this API Key is provided as an HTTP Header. Click on the Send as Query String... to send the API Key and Secret as a query parameter instead.
If the secret provided needs to be Base64 encoded, click on the
Encode Secret... option.
Example: ActiveCampaign
The ActiveCampaign service uses API Keys for authentication.
- URI: https://COMPANYNAME.api-us1.com/api/3/
- Authentication: API Key
- Parameter: Api-Token
- API Key: SECRET provided by ActiveCampaign
Basic Authentication
For HTTP/S Services that require user authentication, choose Basic. This setting requires two values: the User ID and a password.
This authentication mechanism always uses an Authorization HTTP Header.
If the secret provided needs to be Base64 encoded, click on the
Encode Secret... option.
Example: Twilio
The Twilio service uses Basic Auth for authentication.
- URI: https://api.twilio.com
- Authentication: Basic Auth
- User Id: Your Twilio Account Id
- Password: SECRET provided by Twilio
- Base64-Encoding: Yes
Token Authentication
For HTTP/S Services that use Token based authentication, choose Token. This setting requires one value: the token value.
This authentication mechanism always uses an Authorization HTTP Header.
If the secret provided needs to be Base64 encoded, click on the
Encode Secret... option.
Bearer Authentication
For HTTP/S Services that use Bearer authentication, choose Bearer. Bearer authentication can be complex to setup but is considered more secure. Most services require a Bearer Token; some also use Refresh Tokens to generate new Bearer Tokens over time.
The following Bearer Token grant modes are supported:
- Authorization Code: this flow requires you to first authenticate to the service using a browser and approve access to your account. To issue tokens using this method, click on the Obtain OAuth Token... link.
- Implicit: Some services do not require user authorization; instead tokens are generated directly using application secrets provided by the service. To issue tokens using this method, click on the Obtain OAuth Token... link.
- Service Tokens: Some services (such as Twitter) provide long-lived Bearer Tokens directly; they are created once by the service and never change; when using long-lived bearer tokens, simply copy and paste the token in the Bearer Token field.
DataZen supports the creation of Bearer Tokens using client-flow authentication. If the service uses client-flow authentication, see the OAuth Tokens section for more information.
Some services, such as Twitter or MailChimp require you to first create an Application in your account, or in a developer account you created with the service provider. In some cases, it may take a few days for your application to be approved. Contact us for assistance if needed.
Session/Custom Authentication
Session-based HTTP/S sessions require additional settings based on their type.
The following session-based authentication methods are supported:
- JWT Authentication
- SOAP Requests
- HTTP/S Requests
JWT Authentication
For HTTP/S Services that use JWT-based session authentication, choose Session/Custom. Configuring JWT Tokens is possible and requires the use of a Private Key.
Session Endpoint
Enter the necessary information to call the session endpoint, such as its URI and the payload
it requires for POST/PUT operations. The payload can use the {jwt} token as a replacement
parameter. For example, the Google Analytics API uses this payload:
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={jwt}
JWT Security Token
If the service endpoint returns a security token, check the Endpoint returns a security token;
this option provides additional options to read the token and use it as the authentication token.
The Response Node is the path to use within the JSON or XML document returned in which the
token will be found.
The token can either be used as Bearer Token header or as part of a Query Parameter
for which the parameter name needs to be specified.
Using the JWT Payload Setup Screen
When a JWT token is used, click on Build JWT Token... to setup the token. You will need to specify the correct settings as required by the Session endpoint. This sample screen shows you the Google Analytics GA4 settings, with custom claims.
SOAP Requests
When sending a request to a SOAP endpoint, such as Form.com, you need to build a SOAP envelope as part of the request, and provide the response node that contains the session token. The Content-Type is set to text/xml.
In this example, the SOAP body is as follows. The {user_name} and {client_secret} tokens are replaced with the ones provided in the Basic Authentication setting.
<?xml version="1.0" encoding="utf-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aut="http://authentication.v81.api.keysurvey.com">
<soapenv:Header />
<soapenv:Body>
<aut:getAuthenticationToken>
<login>{user_name}</login>
<password>{client_secret}</password>
</aut:getAuthenticationToken>
</soapenv:Body>
</soapenv:Envelope>
Since this call returns an XML payload with the session token in a node called return, the Response Node is set to an XPath query: //return.