Introduction

We need to tell Patchworks what authentication methods can be used when someone chooses to add an instance of your connector, for use in process flows.

Any authentication methods added here will be available to users when they choose to add an instance of this connector - for example:

Supported authentication types

Patchworks supports the following authentication types:

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

Working with authentication methods

Please see Adding a new authentication method for general steps required to add a new authentication method for a connector.

You'll find detailed information about options and settings in the Authentication method options section, and step-by-step examples for each type in the Supported authentication types section.

Introduction

The connector builder supports a range of authentication types. Before a connector can be used (i.e. before instances of it can be added for use in process flows) you must add at least one authentication method for your connector.

The steps and settings required will vary depending on which authentication type you choose to configure, but the general process is straightforward.

What you need to do

General steps are provided below, with links to detailed guidance for each of our supported authentication types.

Step 1 Click the add new authentication method button:

Step 2 You're prompted to enter some basic details for this authentication method:

Complete these details using the table below as a guide:

Step 3 Click the create button to confirm your updates. Basic details are saved and additional setup options are displayed over a series of 'metro stop' tabs - for example:

Step 4 Step through each tab and set configuration options as appropriate for your chosen authentication method.

Configuring an authentication method

For any authentication method, the following configuration options are available:

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.

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

Introduction

The connector variables tab displays any i that you defined in - 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:

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.

In this section

Introduction

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

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

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.

Adding auth variables

To add an auth variable, follow the steps below:

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:

• 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.

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

In this section

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

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 custom script should be created which extracts the token element of the detail field and applies this as the {{variable}} value.

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

3. A user adds an instance 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:

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

This page walks through the steps required to configure basic authentication for a connector.

Here, we're using WooCommerce as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous connector variables and authentication method options sections - we advise getting familiar with these before attempting steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application.

• Ensure that you have all required credentials for testing.

• We recommend using Postman to test any authentication methods that you're adding for a connector.

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that basic authentication is supported, and for any special requirements.

For our example, we can see that basic authentication is permitted and that we need to pass consumer_key as the username and consumer_secret as the password:

Step 2 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to basic and enter the required URL from your API documentation. Click the create button when you've finished, for more configuration options - for example:

Step 6 By default, the basic authentication type includes two required auth variables - username and password:

If your API documentation requires users to provide an actual username and password to authenticate this connector, these can be left as they are. However, many APIs expect alternative information to be passed as these fields.

Taking our example, the WooCommerce API documentation states that a consumer key should be provided as the username and a consumer secret should be provided as the password:

As such, we need to rename the default username and password fields. To do this, click the field name and update the display name as appropriate - we do this for both username and password:

If required, you can add more auth variables here.

Step 7 With username and password fields renamed (or not) as required, we now need to define where any information that users provide for these fields should be injected into the API request. For basic authentication, these details are always passed in request headers.

To set this up, click the header tab, followed by the add new header button.

Step 8 You can now enter your authentication options as key pairs:

Here, the key is the name of the parameter that you're passing in as the username / password, as defined in the API documentation for your third-party application. Taking our example, we know that the consumer_key is required for username and consumer_secret is required for password:

So, our key pair for username would be defined as follows (injecting consumer_key information into the {{username}} variable:

And our key pair for password would be defined as follows (injecting consumer_secret information into the {{password}} variable:

Step 9 This completes our setup for basic authentication. Now, when someone chooses to add an instance for this connector, basic authentication will be an option that they can choose. If selected, the user will then be prompted to enter a username and password - or in the case of our example - a consumer key and a consumer secret:

Next steps

When you configure a process flow connection shape to use a given instance, you can then choose from a list of available endpoints. For example:

This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.

So, having added a new authentication method, you must enable it for any connector endpoints that you might want to use with instances that are added using this authentication method.

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

Basic authentication is the simplest (though not the strongest) method for authenticating API requests.

With basic authentication, a username and password are sent in the HTTP header of each API request, to authenticate a client application (in this case, Patchworks) and grant access to the associated resource.

How it works

Here's how basic authentication works:

1. The client-server (i.e. Patchworks) sends an API request to the required third-party application server (e.g. Shopify). The request includes username and password authentication credentials in the HTTP header of the request, encoded in Base64 format.

2. Upon receipt of the request, the third-party application server extracts authentication credentials from the header. It then validates these credentials by comparing them with the stored user credentials in its own system/database.

3. If the credentials provided are valid, the third-party application server grants access to the requested resource. If the credentials are invalid or missing, the third-party application server denies access and returns an appropriate error response.

User experience of basic authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with basic authentication, they will see something similar to the example below:

Basic authentication examples

It can be useful to compare how existing connectors have been configured for token-based authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

• Configuring basic authentication

Introduction

This page walks through the steps required to configure token authentication for a connector.

Here, we're using as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous and sections - we advise getting familiar with these before attempting the steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application (we're using as an example).

• Ensure that you have all the required credentials for testing.

• We recommend using to test any authentication methods that you're adding for a connector.

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that token authentication is supported and for any special requirements. Looking at the authentication section in Shopify's API documentation, there are three key points to note:

1. Whilst OAuth is the authentication method used to generate tokens when Shopify custom apps are installed, we've retrieved our generated token from the Shopify admin portal and will use this to set up token-based authentication.

2. We must pass our token into request headers, via a parameter called X-Shopify-Access-Token .

3. All requests must include a store_name value.

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to token-based and enter the required URL from your API documentation. Click the create button when you've finished, for more configuration options - for example:

Step 7 Now we need to define where information that users provide for these fields should be injected into the authentication requests.

You can edit this option as needed - or remove it from the header altogether if your API documentation requires an alternative approach for passing in tokens.

At the very start of this exercise, we noted that our Shopify token must be passed into request headers via a parameter called X-Shopify-Access-Token . So, we can edit the default authorisation option to reflect this:

Don't forget to save any changes that you make.

To do this:

1. Click the connector variables tab.

2. Click the use button associated with the variable we want to use for our new authentication method.

3. That variable is added to token-based authentication as an auth variable.

Step 9 This completes our setup for token-based authentication. Now, when a user adds an instance of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables (in our example, store name and token).

Next steps

This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.

Introduction

OAuth 2 is a protocol which allows users to grant limited access to their resources/data in an application or service (e.g. NetSuite), to another application or service (in this case, Patchworks) without ever sharing their login credentials.

The authentication flow and associated configuration for OAuth 2 vary according to which grant type is used. Patchworks supports the following OAuth 2 grant types:

OAuth 2 provides a more streamlined, standardised approach than - it’s easier to implement and more suitable for a wide range of applications.

Introduction

This page walks through the steps required to configure OAuth 2 authentication (authorisation code flow) for a connector.

Here, we're using as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous and sections - we advise getting familiar with these before attempting steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application (we're using as an example).

• Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed. For example, includes a section on tasks that administrators must complete to support OAuth 2 for integrations.

• Ensure that you have all required OAuth 2 credentials for testing.

• We recommend using to test any authentication methods that you're adding for a connector.

Redirect URIs

When specifying redirect URIs for OAuth 2, the following values can be used:

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that OAuth 2 authentication (authorisation code flow) is supported, and for any special requirements.

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to OAuth 2 authorisation code and enter the required URL(s) from your API documentation.

Click the create button when you've finished, for more configuration options - for example:

To do this:

1. Click the connector variables tab.

2. Click the use button associated with the variable we want to use for our new authentication method.

3. That variable is added to this authentication method as an auth variable.

Step 8 Next, we need to confirm/change where any information that users provide for auth variables should be injected into authentication requests.

Default auth variables are pre-configured to be passed into API requests, as most commonly needed. For example, if we check the URL parameters tab now, we'll see that some of our user-provided auth variables have been added automatically:

And if we check the body tab now, we'll see that remaining user-provided auth variables have been added automatically:

Check the API documentation for your third-party application and ensure that all required auth variables have been added, and are being passed in the right place. Don't forget to save any changes that you make.

Next steps

This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.

Introduction

The OAuth 2 client credentials flow allows client applications (i.e. Patchworks) to authenticate and obtain access to resources, without involving specific user intervention.

How it works

The exact mechanism used for client credentials authentication depends on the implementation of the authorisation server for the system in question, but a common mechanism is client secret.

This is where a client application (in this case, Patchworks) authenticates itself by sending its unique client identifier and client secret to the authorisation server, and receives a token in response.

OAuth 2 (client credentials) authentication examples

It can be useful to compare how existing connectors have been configured for OAuth 2 (client credentials) authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

• Configuring OAuth 2 authentication (client credentials)

Introduction

Token-based authentication allows users to verify their identity with a third-party server using a token. This is a more secure approach than basic authentication because username and password credentials are never passed in API requests.

How it works

Token-based authentication works by authenticating with a token that you already have available - perhaps it was given to you by a third-party application provider, or you have generated a token from the API - it doesn't matter how you obtain the token.

User experience of token authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with token-based authentication, they will see something similar to the example below:

Token-based authentication examples

It can be useful to compare how existing connectors have been configured for token-based authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

• Configuring token-based authentication

Introduction

The OAuth 2 authorisation code flow requires a user (in this case, a Patchworks user, adding a connector instance for use in process flows) to log into an authorisation server and grant permission for Patchworks to access the required data.

How it works

When a Patchworks user adds an instance of a connector and chooses to authenticate with OAuth 2 (authorisation code) they are directed to the authorisation server for a third-party service, where they log in and 'allow' requested access. A sample user journey for NetSuite is shown below:

Here, we:

1. Add an instance and confirm credentials.

2. Are redirected to NetSuite, where we log in.

3. Are presented with information about what access is being requested, and choose to proceed.

4. Return to the Patchworks connector page, where our new NetSuite instance is added and ready to use in process flows.

Authentication request URLs

When setting up OAuth 2 (authorisation code) authentication, two URLs are required. The first (URL) is the authentication endpoint and the second (Additional URL 1) is the authorise endpoint.

The following example is for a NetSuite implementation - please check your API documentation for your own required values:

Redirect URIs

When specifying redirect URIs for OAuth 2, the following values can be used:

OAuth 2 (authorisation code) authentication examples

It can be useful to compare how existing connectors have been configured for OAuth 2 (authorisation code) authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

• Configuring OAuth 2 authentication (authorisation code)

Introduction

Typically, users need to provide valid authentication credentials for any instance of a connector that they add - when the instance is created, Patchworks checks that the credentials are valid and if they are, the instance is created.

However, there may be times where you wish to allow users to add an instance without providing any authentication credentials - perhaps you're connecting to a public-facing system, or to a Postman mock server (for example).

User experience of token authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with a configured no auth authentication method, they are not prompted to enter any credentials. Instead, they go directly to finalising the instance - for example:

Introduction

This page walks through the steps required to configure no auth authentication for a connector.

The Steps

Step 1 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 2 Access authentication details:

Step 3 Click the add new authentication method button:

Step 4 Complete basic details for this authentication method - ensure that you set the authentication type to no auth (public) - for example:

Step 5 You don't need to add any settings under authentication setup - although if you want users to provide variable values when they add instances for this connector, or pass in header/body content, etc. then you can update these tabs:

Step 6 Save changes.

Introduction

OAuth 1.0 involves the use of cryptographic signatures for message integrity and verification. It requires the consumer (in this case, Patchworks) to sign API requests using a consumer secret, which is provided by the service provider. The service provider verifies these signatures to ensure the integrity of the requests.

Patchworks supports the following signature methods:

• HMAC-SHA256

OAuth 1.0 has been largely superseded by .

How it works

Here's how OAuth 1 authentication works:

OAuth 1 authentication examples

It can be useful to compare how existing connectors have been configured for OAuth 1 authentication.

Introduction

This page walks through the steps required to configure OAuth 2 authentication (client credentials flow) for a connector.

Here, we're using as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous and sections - we advise getting familiar with these before attempting steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application (we're using for this example).

• Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed.

• Ensure that you have all required OAuth 2 credentials for testing.

• We recommend using to test any authentication methods that you're adding for a connector.

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that OAuth 2 authentication (client credentials code flow) is supported, and for any special requirements.

Step 2 Log in to the and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to OAuth 2 client credentials and click the create button.

The following parameters are required for the OAuth 2 client credentials flow, and are configured to be displayed to users when they attempt to add an instance for this connector:

Step 7 Check your API documentation for any additional parameters that are required for authentication - do you need users to provide any additional information to authenticate instances of this this connector?

Also check your API documentation for any query parameters required for this URL and add them as needed.

For OAuth 2 (client credentials), a content-type parameter is added by default, with a value of application/x-www-form-urlencoded. Check your API documentation - if necessary you can change this value.