Introduction

Any key pairs added to the header tab are passed into authentication request headers - for example:

In this example, we've already defined two auth variables for username and password, so users will be prompted to enter these details when adding an instance of this connector for use in process flows.

How we then pass this information into API requests is determined by the API documentation for the underlying third-party application. Often, these details are passed in request headers, but sometimes it will be via the request body.

By adding these as key pairs to the header, we pass any values provided for these fields in the authentication request headers.

You should refer to the authentication section of your your API documentation for specific guidance about what (if any) values need to be passed in authentication request headers. For example, in Shopify, it's noted that we need to send two values in the request header - Content-Type and Shopify-Access-Token:

Adding header parameters

Header parameters are added as key pairs. To add a header parameter, follow the steps below:

Step 1: Click the add new header button:

Step 2: Complete key pair details as required and save changes:

Editing & removing header parameters

Header parameters are standard key pairs - techniques for working with these parameters are the same as those for working with body parameters, URL parameters, etc. For more information about these techniques, please see the Working with parameters page.

Introduction

Any key pairs added to the body tab are passed into the request body for authentication requests - for example:

By adding these as key pairs to the body, we pass any values provided for these fields in the authentication request body.

In this example, we need to pass a number of credentials for OAuth 2 authorisation into the body. Notice that the values in this example are defined as variables. We've already defined auth variables for these items, which means users will be prompted to enter these details when adding an instance of this connector for use in process flows. So, required body parameter values will use values that users have provided when the instance being used was created.

Adding body parameters

Body parameters are added as key pairs. To add a body parameter, follow the steps below:

Step 1: Click the add new required body parameter button.

Step 2: Complete key pair details as required and save changes - for example:

Editing & removing body parameters

Body parameters are standard key pairs - techniques for working with these parameters are the same as those for working with header parameters, URL parameters, etc. For more information about these techniques, please see the Working with parameters page.

Introduction

The connector variables tab displays any instance-level, shared variables that you defined in Step 2: connector variables - for example:

Using a connector variable in your authentication method

If you want to use any of these variables in this authentication method, click the use button:

This copies the variable into the auth variables tab - for example:

From here, the variable is treated like any other auth variable - you will need to set options to determine if/how this variable is displayed to users, and how any values for it should be passed in API requests for authentication.

Removing a connector variable from auth variables

If you choose to use a connector variable- i.e. to copy it to the auth variables tab - but later change your mind - you can remove it by clicking the associated trash icon on the auth variables tab - for example:

This clears the connector variable from the auth variables tab but the original 'shared' connector variable remains available for future use.

Introduction

The auth variables tab is used to define authentication variables for any values that you need users to provide when they choose to add an instance of this connector, for use in process flows:

Here, you define what fields a user will be asked to complete when they choose to add an instance, select and authentication method, and provide credentials. For example:

You also define how any provided values are passed in authentication requests - i.e. are they included in the API request URL, the header, or the body?

Default auth variables

Having chosen an authentication method to configure, any required variables for that method are listed by default - for example:

These are variables that are always required to authenticate using this authentication method. You can't remove or change the behaviour of these variables, but you can change the display name if required.

Default auth variables are pre-configured to be passed into API requests as needed. For example, token-based authentication has one default parameter, which is pre-configured on the header tab. If your requirements are different, you can change how/where these variables are used.

Adding auth variables

To add an auth variable, follow the steps below:

Step 1 Start by selecting the connector variables tab to check if there are any instance-level variables for this connector that you want to include. Any variables defined for the instance as a whole are shown here - click the use button for any that you wish to include as an auth variable - for example:

When you choose to use a connector variable, you'll see that it gets added to the auth variables tab - for example:

Step 2 Back in the auth variables tab, you can now add any other variables for information that you need to provide when they add an instance of this connector with this authentication method. To do this, click the add variable button:

Step 3 Complete details and set options on the add variable page:

The add variables page is the same for all types of variables that you may encounter in the connector builder (for information about these options please see the Working with variables page). However, it's worth noting the effect of setting required and configurable by user options in the context of auth variables:

• When you add an auth variable and choose to make it required, you are effectively saying: 'When a user adds an instance of this connector, do not allow them to proceed without providing a value for this variable'.

• When you add an auth variable and choose to make it only configurable by users, you are effectively saying: 'When a user adds an instance of this connector, allow them to provide a value for this variable if they have one but if they don't, let them proceed'.

Step 4: Click the save button.

Step 5 Having added a variable, make sure that you go on to define how any values captured for it should be passed in API requests. Typically, any user-provided variable that you define here would then be added to the authentication request URL path, authentication request URL parameters, the authentication request header, or the authentication request body for the authentication method.

Introduction

Pre-request scripts allow you to modify authentication request parameters before sending the actual request. You can set dynamic values, compute signatures, or add headers based on specific conditions.

For example, you may have a third-party application which only accepts user passwords which are base 64 encoded. Expecting your users to know how to encode their password when they need to add connector instance for this application isn't always realistic, so a pre-request script can take care of this automatically.

How it works

Let's use the example scenario above to break down how pre-request scripts work:

1. A custom script should be created which takes a given password and performs base 64 encoding.

2. This script is applied to the pre-request script tab for the appropriate authentication method.

3. A user chooses to add an instance using this authentication method, and enters their username and password. Typically, an authentication request would be sent at this point - but NOT if a pre-request script is associated with the authentication method.

4. The pre-request script defined for this authentication method runs - any required values from authentication variables provided by the user are taken to manipulate the authentication request body as needed.

5. The authentication request is sent to to the given endpoint, including the manipulated body content.

6. Once the script has run, the authentication request is made, including the encoded password.

Applying a pre-request script

Step 1 Select the pre-request script tab for your authentication method:

Step 2 Click in the select a script field and choose the script that you want to use - for example:

Step 3 Choose the script version that you want to use:

Step 4 Now you can review the script code to be applied and save changes:

Introduction

URL parameters are used to apply queries/filters to the authentication request URL:

Any parameters added here are appended to the authentication URL as a query.

Using URL parameters in authentication requests

In reality, it's unlikely that URL parameters will be commonly used when defining authentication methods however, you can absolutely add them if needed.

URL parameters are added as 'key pairs' - so you specify a 'key' (a valid field name for this API) and then the required value.

Static values

A URL parameter value can be static - for example:

In this case, the value would be appended to the request endpoint as a URL query with the value exactly as it is defined - for example:

Dynamic values

...and when a process flow runs for this connector, associated API requests are injected with this value wherever a {{warehouseID}} variable is found. So, if we've added this variable in a URL parameter, as below:

...the resulting API request would include a parameter for whatever Warehouse ID the user entered when the instance being used was created.

Adding URL parameters

URL parameters are added as key pairs. To add a URL parameter, follow the steps below:

Step 1: Click the add new parameter button:

Step 2: Complete key pair details as required:

Step 3 Click the save button.

Editing & removing URL parameters

Introduction

Post-request scripts are useful for manipulating the response data before displaying or using it. You can extract specific values, format data, or even perform calculations. This helps in preparing the response data for further requests, or for displaying in a more user-friendly manner.

For example, we might have a connector which expects API requests to be authenticated with a {{token}} value received in response to an authentication request. However, suppose that the authentication request response includes the required token value AND a client_id value in the same detail field - somehow we need to ensure that only the token element is injected into a {{token}} variable, to be used for authenticating subsequent API requests.

To achieve this, we could create a custom script to extract the the token element from the detail field and then apply this to the post-request script tab for the required authentication method.

How it works

Let's use the example scenario above to break down how post-request scripts work:

1. A which extracts the token element of the detail field and applies this as the {{variable}} value.

2. This script is for the appropriate authentication method.

3. A user using this authentication method, and enters their username and password.

4. The authentication request is sent and a successful response is returned, with client id and token values in the same detail field.

5. The post-request script defined for this authentication method runs, extracting the token element from the detail field and injecting it into the {{token}} variable for the authentication method.

Applying a post-request script

Step 1 Select the post-request script tab for your authentication method:

Step 2 Click in the select a script field and choose the script that you want to use - for example:

Step 3 Choose the script version that you want to use:

Step 4 Now you can review the script code to be applied and save changes:

In this section