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.
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:
Add an instance and confirm credentials.
Are redirected to NetSuite, where we log in.
Are presented with information about what access is being requested, and choose to proceed.
Return to the Patchworks connector page, where our new NetSuite instance is added and ready to use in process flows.
If you'd like more detailed information about how OAuth 2 authorisation code authentication works, there's some great background information on the Postman website.
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:
When specifying redirect URIs for OAuth 2, the following values can be used:
Production
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.
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.
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.
When specifying redirect URIs for OAuth 2, the following values can be used:
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.
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 OAuth 2 authorisation code and enter the required URL(s) from your API documentation.
For 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. Please refer to your API documentation for these values.
Click the create button when you've finished, for more configuration options - for example:
Consider the following when setting your client_type parameter value:
confidential . Setting this value means that when a second call is made to get a token, basic auth is added to the header using the client_id and client_secret.
public (or any other value). Setting this value means the second request does not send authorisation in the header.
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.
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 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.
This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.
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 OAuth 2 authorisation code type includes a range of default :
These are known variables that a user must provide to using this authentication method.
Mandatory variables are locked however, you can if required. You can also add more here if needed.
Step 7 Now we'll check to see if there are any shared that need to be used as auth variables.
In our example, we need to use the accountid connector variable for authentication, because this is a user-provided value that forms part of our authentication request URL path (defined in step 5). So, we can simply choose to use the accountid connector variable as an for this authentication method:
Every API will have its own requirements for variables that are required for authentication with a given method. Remember that you can add new and/or variables as needed.
Step 9 This completes our setup for OAuth 2 authorisation code authentication. Now, when a user of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables. Upon confirmation, they will be directed to your third-party authorisation server and asked to authorise access - then redirected back to Patchworks.
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 .
Staging
Production
