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.
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.
If you'd like more detailed information about how Token authentication works, there's some great background information on the Postman website.
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:
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.
This page walks through the steps required to configure token authentication for a connector.
Ensure that you have all required credentials for testing.
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:
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.
We must pass our token into request headers, via a parameter called X-Shopify-Access-Token
.
All requests mu.st include a store_name
value.
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:
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.
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:
Click the connector variables tab.
Click the use button associated with the variable we want to use for our new authentication method.
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).
This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.
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.
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).
We recommend using to test any authentication methods that you're adding for a connector.
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 6 By default, the token-based authentication type includes one required - token:
These are known variables that a user must provide to using this authentication method. Mandatory variables are locked however, you can if required.
If required, you can add more here.
Commonly, tokens are passed into request - as such, a default authorisation option is ready to use:
We leave the value set to {{token}}
, so when a user 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:
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 of this connector using token-based authentication (in addition to the token value we defined earlier).
We already have a store_name
defined, so we can simply choose to 'use' it as an for token-based authentication:
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 and/or variables as needed.
When you configure a to use a given instance, you can then choose from a list of available . For example:
So, having added a new authentication method, you must .