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.

In this section

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

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

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

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

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

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

How it works

When a Patchworks user 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

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

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

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

Here, we're using Shopware 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 (we're using Shopware API docs 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 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 OAuth 2 authentication (client credentials code flow) is supported, and for any special requirements.

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 OAuth 2 client credentials and click the create button.

Step 6 Authentication variables are displayed. By default, the OAuth 2 client credentials type includes a range of default authentication variables:

These are known variables that a user must provide to authenticate an instance of this connector with this authentication method.

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:

In each case, you can change the parameter name, default value and settings for how the field is made available to users when they choose to add connector instances. You cannot change the parameter key.

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?

Step 8 Select the URL parameters tab and provide a request URL for authentication - you'll find this in your API documentation:

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

Step 9 Select the header tab and add any authentication variables that need to be passed in the authentication request header - you'll find this in your API documentation:

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.

Step 10 Select the body tab and add any authentication parameters/content to be passed in the authentication request body - you'll find this in your API documentation.

Step 11 This completes our setup for OAuth 2 (client credentials) 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.

Introduction

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

The Steps

Step 1 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 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

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 token authentication for a connector.

Here, we're using Shopify 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 the steps detailed here.

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

• Ensure that you have all the 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 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 2 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all 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 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 6 By default, the token-based authentication type includes one required auth variable - token:

If required, you can add more auth variables here.

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

Commonly, tokens are passed into request headers - as such, a default authorisation option is ready to use:

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:

We leave the value set to {{token}}, so when a user adds an instance of this connector using token-based authentication and provides a valid token, the value they provide will be injected into this variable and passed in the request header:

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

Step 8 Remember that at the very start of this exercise, we noted that a store_name value must be passed in the URL for all Shopify API requests. To achieve this, we need to ask users to provide a store_name value when they add an instance of this connector using token-based authentication (in addition to the token value we defined earlier).

We already have a store_name connector variable defined, so we can choose to 'use' it as an auth variable for token-based authentication:

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

When configuring a process flow connection shape to use a given instance, you can 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

SOAP (Simple Object Access Protocol) is a messaging protocol for exchanging structured information in a web environment. SOAP authentication is used specifically for authenticating SOAP-based web services.

How it works

The Patchworks Connector Builder incorporates token-based authentication for SOAP. When requests are made, user credentials (provided when the connector instance was created) are passed for authentication and a token is returned - tokens are incorporated into SOAP messages.

Your authentication setup will typically include variables for user credentials (e.g. username and password) and a response_authentication_token_key (or similar) which tells Patchworks where to find a token in authentication response SOAP messages. For example:

User experience of SOAP authentication

Required variables will vary, depending on the API but in general there will be at least fields for users to enter their credentials.

SOAP-based authentication examples

It can be useful to compare how existing connectors have been configured for SOAP-based authentication. Some examples are linked below:

You can install any of these for comparison.

Related information