Create a custom OAuth connection

When do I need to create a custom OAuth connection?

• The API you want to connect to only provides access via OAuth, not API keys or any other authorization method.

• Data Fetcher does not have a preset OAuth connection for the API.

1. Set up an app with the service that provides the API

Most APIs will require you to set up an app in a developer section of your account. Check the OAuth / Authorization section of the API documentation to find out the exact steps to take. It will generally involve clicking a few buttons and adding an app name, although sometimes the process is longer and requires the service to review your app.

When configuring the app, you will usually be asked for a redirect URL. This is the Data Fetcher redirect URL that you should use:

https://oauth.datafetcher.com/auth/callback

After you've set up the app, you will be provided with a client ID and client secret. Make a note of these somewhere safe.

2. Create a Custom OAuth Connection in Data Fetcher

• Create a custom request in Data Fetcher.

• Click on the Authorization tab.

• For the Type, select OAuth.

• Click the + New button.

• At the bottom of the modal that opens, click create custom OAuth connection. This will open the custom OAuth connection screen, where you can enter the details of the API:

  • Name: a name that will remind you what this OAuth connection is.

  • Auth type: the OAuth type. Most OAuth APIs use OAuth 2, but check the API documentation.

  • Authorization URL: the URL used for the authorization request, when Data Fetcher will open a new tab and ask for permission to access the API. This is typically something like https://example.com/oauth/v2/auth.

  • Authorization Parameters: the parameters that will be added to the Authorization URL when making the authorization request. The API documentation will list these. Data Fetcher will automatically include the standard OAuth parameters (response_type,client_id,redirect_uri,response_type,state,client_secret).

  • Token URL: the URL used after the authorization request to generates access tokens from the authorization code. This is typically something like https://example.com/oauth/v2/token.

  • Token Parameters. The parameters that will be added to the Token URL when making the token request. Data Fetcher will automatically add the grant_type=authorization_code parameter.

  • Client ID: the app client ID from step 1.

  • Client secret: the app client secret from step 1.

  • Scopes (comma separated): a comma separated list of the scopes that you want to access for this API. You can find these in the API documentation.

  • Request Headers: the headers to be supplied with every request when using this custom OAuth connection. The most important one to add here, to ensure the OAuth access tokens are actually used, is a header with the name Authorization and a value of Bearer ${auth.accessToken}. This syntax allows you to access any values that were returned by the authorization request.

  • Base URL: the base URL that all requests to this API use. e.g. https://example.com/api/ .

• After you've entered all these details, click Create connection. Data Fetcher will begin the authorization request in a new tab. If everything has been entered correctly, you will be able to authorize Data Fetcher to access the API and use this custom OAuth connection in any custom Data Fetcher request.

Custom OAuth Connection Example

Let's connect to the Zoho People APIs as an example.

1. First, we go to the Zoho API Console and register a new client. We are given a client ID and client secret.

2. Now we need to add the client ID, client secret and other details in Data Fetcher by following the steps above. The Zoho Peoples API OAuth documentation provides all the values we need.

Auth type	OAuth 2
Authorization URL	https://accounts.zoho.com/oauth/v2/auth
Authorization Parameters	prompt=consent access_type=offline
Token URL	https://accounts.zoho.com/oauth/v2/token
Client ID	Client ID from step 1.
Client secret	Client secret from step 1.
Scopes	ZOHOPEOPLE.forms.ALL
Request headers	Authorization=Bearer ${auth.accessToken}
Base URL	https://people.zoho.com/people/api/