> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/supported-authentication-types/oauth-2/oauth-2-authorisation-code/configuring-oauth-2-authentication-authorisation-code.md).
# Configuring OAuth 2 authentication (authorisation code)
## **Introduction**
This page summarises the configuration for the `OAuth 2 authentication (authorisation code flow)` authentication method.
## Preparation
* For this task, we'll be using techniques described in previous [connector variables](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/connector-variables.md) and [authentication method options](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options.md) sections. We advise getting familiar with these before attempting the steps detailed here.
* Ensure you have API documentation for your third-party application to hand.
* Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed. For example, [NetSuite's documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771171166.html#OAuth-2.0-Tasks-for-Administrators) includes a section on tasks that administrators must complete to support OAuth 2 for integrations.
* Ensure that you have all the required OAuth 2 credentials for testing.
* We recommend using [Postman](https://www.postman.com/) to test any authentication methods that you're adding for a connector.
## Redirect URIs
When specifying redirect URIs (also known as callback URLs) for OAuth 2, the following values can be used:
## The Steps
{% stepper %}
{% step %}
**Review OAuth 2 requirements for the API**
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.
{% endstep %}
{% step %}
**Edit the required connector**
Log in to the [Patchworks dashboard](https://app.wearepatchworks.com/login) 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:
{% hint style="info" %}
If you're building a new connector, you can pick up these steps when you reach the `authentication` section of the connector builder.
{% endhint %}
{% endstep %}
{% step %}
**Access authentication details**
Select the `authentication` option:
{% endstep %}
{% step %}
**Add a new authentication method**
Click the `add new authentication method` button:
{% endstep %}
{% step %}
**Add a new authentication method**
Complete basic details for this authentication method, using the table below as a guide:
Field
Summary
Enter a name...
The name to be displayed to users when this authentication method is shown.
Select an authentication method
Select OAuth 2 Authorisation Code from the dropdown list.
Timeout limit
Set the number of seconds to wait for an authentication request to complete before timing out.
Enter a link to documentation
It's often useful to provide a link to the API documentation that you are working from to configure this authentication type. Adding a link here ensures that the relevant documentation can be accessed easily if you or someone else needs to edit/understand this configuration later.
For example:
{% endstep %}
{% step %}
**Create this authentication method**
Click the `create` button to confirm details - for example:
The authentication method is saved, and configuration options are displayed in the `authentication setup` panel, over a series of tabs. For example:
The same set of tabs is displayed for any authentication type, but the default options may vary depending on the authentication type you have chosen to configure.
{% hint style="info" %}
For general information about these configuration tabs, please see [Authentication method options](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options.md).
{% endhint %}
{% endstep %}
{% step %}
**Review & update authentication variables**
By default, a range of default [auth variables](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/auth-variables.md) is included - these are typically expected for the `OAuth 2 authorisation code` authentication type. For example:
These are variables that must be passed in when a user attempts to [authenticate an instance of this connector](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md). Values might be set as default, or provided by the user during the instance creation process.
You should review/update/add/remove authentication variables according to the API documentation for your connector. Some general guidelines are summarised below.
| Variable | Notes |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `State length` | This is a numeric value which determines the length of a random string generated (behind the scenes) during the OAuth process, for verification purposes. |
| `Scope` | Determines the scope of access that Patchworks will have to associated data. |
| `Client ID` & `Client secret` | These credentials allow Patchworks to authenticate and interact with your third-party system. |
| `Response authentication token key` | Tells Patchworks where to find the auth token in your system's response. Typically set to `access_token`. |
| `Grant_type` |
Tells the OAuth server what kind of request you're making and what credentials you are providing to prove your identity. Typical options for OAuth 2 authorisation code are:
grant\_type=authorization\_code The server checks the code and returns a token.
grant\_type=refresh\_token. A refresh token is provided, which proves prior authorisation. This is used to retrieve a new token.
Note that some systems will use the grant\_type parameter to handle authorisation and refresh tokens, whereas others will use a separate parameter (e.g. refresh\_grant\_type) for refresh tokens. Your API documentation should guide you on this.
|
| `Response type key` |
Determines what is returned from the authentication request. The most typically used option for OAuth 2 authorisation code is code. This sets an authorisation code and appends it to the given callback URL.
This code is then exchanged for an access/refresh token (depending on the associated grant type).
|
| `OAuth Authorised Code` | This advanced setting is not required for general use. |
| `Dashboard OAuth Callback URL` | Sometimes known as a `redirect url`, this is the address used for returning the authorisation code. The default value is: `https://app.wearepatchworks.com/oauth/authenticate`. Typically, this should not be changed. |
| `Refresh Grant type` | Some systems will use the `grant_type` parameter to handle authorisation and refresh tokens, whereas others will use a separate parameter for refresh tokens (e.g. `refresh_grant_type` set to `refresh_token`). Your API documentation should guide you on this. |
| `Response Refresh Token Key` | Tells Patchworks where to find the refresh token in your system's response. Typically set to `refresh_token`. |
{% hint style="warning" %}
Some APIs are case-sensitive when it comes to adding variables. Be sure to enter key names exactly as they are specified in the API documentation.
{% endhint %}
{% endstep %}
{% step %}
**Review & update URL parameters**
For `OAuth 2 (authorisation code` authentication, you can specify three URLs:
| URL | Notes |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL / Token URL |
Used to obtain a token, based on the code that is returned from the Authorise URL request. For example:
|
| Authorise URL |
This URL is triggered when a user chooses to save an instance of this connector. Typically, it's a page in your third-party system where the user can confirm that access is allowed. For example:
|
| (Optional) Re-authenticate URL |
If you are using refresh tokens, this is the URL to be used. For example:
|
| {% endstep %} | |
{% step %}
**Review & update remaining configuration tabs**
There are no special considerations for configuration options on the remaining tabs. Check the API documentation for your third-party system and update these as needed.
{% hint style="info" %}
For general guidance on these tabs, refer to the [Authentication method options](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options.md) section.
{% endhint %}
{% endstep %}
{% step %}
**Test authentication**
This completes our setup for `OAuth 2 authorisation code` authentication. Now, when a user [adds an instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables. Upon confirmation, they are directed to your third-party authorisation server and asked to authorise access - then redirected back to Patchworks.
{% endstep %}
{% endstepper %}
## Next steps
When you configure a [process flow connection shape ](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md)to use a given `instance`, you can then choose from a list of available [endpoints](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints.md). For example:
This list only includes 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](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/enabling-an-authentication-method-for-an-endpoint.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/supported-authentication-types/oauth-2/oauth-2-authorisation-code/configuring-oauth-2-authentication-authorisation-code.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.