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 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 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 mu.st include a store_name value.

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:

If you're building a new connector, you can pick up these steps when you reach the authentication section of the connector builder.

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:

These are known variables that a user must provide to authenticate an instance of this connector using this authentication method. Mandatory variables are locked however, you can change the display name if required.

If required, you can add more auth variables here.

Some APIs are case sensitive when it comes to adding variables - be sure to enter key names exactly as they are specified in API documentation.

Step 7 Now we need to define where any 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 simply 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

Every API will have its own requirements for variables that are required in addition to a {{token}}. In our example, we already had a store_name variable ready to use but you can add new connector and/or auth variables as needed.

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

Show me