Configuring token-based authentication

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:

Show me

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.

Show me

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.

Show me

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

Show me

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.

Show me