This tutorial will guide you through using the Synatic HTTP Service source step to connect to an API using OAuth 2.0 authentication. We will use QuickBooks API for this tutorial and connect using OAuth.
You will learn how to:
We are going to access the simplest endpoint on QuickBooks that requires authentication:
https://sandbox-quickbooks.api.intuit.com/v3/company/4620816365162546440/companyinfo/4620816365162546440
When you execute the API request, the response will return your QuickBooks Company Info.
Watch the video below to learn how to create a flow using the HTTP Service using OAuth 2.0 authentication to connect to an API.
The following sections explain each step of the process, as shown in the video.
Create the initial Synatic Flow
In Synatic, create a new Flow in your Solution.
Click ⨁ to add a new Flow.
Give the Flow a name, like "HTTP Service using QuickBooks OAuth2" and a short meaningful description.
Click Save.
Add a JSON step
Because we will be receiving a JSON Object from the QuickBooks API, we must add a JSON step to the Flow.
The JSON step is located in the Reader drawer in the Steps palette. Select and drag it onto the flow canvas to the position shown.
The JSON step opens. You can click to save it as no configuration is required.
Add an HTTP Service step
The HTTP Service step is located in the Source drawer in the Steps palette.
To add the HTTP Service step to the Flow:
Select and drag the HTTP Service step in front of the JSON step.
Give the step a name, like "HTTP Service using QuickBooks OAuth2" and a short meaningful description.
Click Save Step.
Create the API OAuth connection
Creating a connection to the API endpoint will require several steps, so click + in the Authentication Method group to create a connection and select OAuth 2 from the Auth Type dropdown.
At this point, you'll notice that the HTTP Authentication connection dialog requires multiple authentication configuration fields to be completed. These fields make up the URLs and credentials to authenticate against the QuickBooks OAuth API.
We'll pause Synatic here for a while to create and register an app on QuickBooks to get the relevant URLs and credentials such as the Client ID and Client Secret required in our connection.
Create a QuickBooks App
To begin the OAuth building process, you must first register a new app with QuickBooks. Here, you will register basic information such as; application name, website, email, etc.
Most OAuth APIs will require you to register an app with them before you can connect. Their processes will be similar to QuickBooks but may require other info or steps.
📝 You can learn more about their requirements by reading the API documentation on their websites.
Go to https://developer.intuit.com/app/developer/dashboard and sign up if you don't already have an account.
Select Create an App.
Select the platform panel you want to create (we're using QuickBooks Online and Payments in this example).
4. Give the App a name, select a Scope, then click Create App.
5. The Client ID and Client Secret access keys are displayed on the Keys & OAuth page in the QuickBooks app. Use these keys to set up OAuth in your Synatic HTTP connection step.
Client ID (This is equivalent to Synatic's Client ID)
This is considered public information and doesn't need to be kept secret. The QuickBooks App ID looks something like ABRrrtz*********06zanoSZrT4.Client Secret (This is equivalent to Synatic's Client Secret)
⚠️ The Client Secret must be kept very confidential and NOT shared at all.
The QuickBooks App ID looks something like 0niw3Yo1********TKqFVaiHe.
Now, select and copy your Client ID and Client Secret, and paste them into the Client ID and Client Secret fields in your Synatic QuickBooks connection:
Also, while you at it, select the following options in Synatic's QuickBooks connection:
Select the Response Type as Code.
- where response_type indicates that your server expects an authorization code, which Synatic can exchange along with your Client Secret for the final bearer access token.Select Grant Type as Authorization Code.
- where grant_type indicates the type of authorization to be granted to Synatic.De-select Use Refresh as Token to disable the use of Long Live tokens.
Select One Use Refresh Token to use only short-lived tokens, which need to be refreshed after a predetermined time.
Select No Query String to disable the addition of a query string of parameters to the API URL.
Redirect URIs
Go to the Redirect URIs panel in the Keys & OAuth page to register the Synatic redirect URI with QuickBooks. This will authorize Synatic as a valid destination to return tokens and codes to.
Synatic uses https://admin.synatic.com/app/public/oauthresponse as its redirect URI.
Click the Add URL button, then paste the Synatic redirect URI into the URI field in the panel dialog, then click Save.
Gather QuickBooks API Call URLs
We going to use the Playground in QuickBooks to get the Base URL and Request URL. At the top of the Keys & OAuth page is a link to the OAuth 2.0 Playground.
Click this link to open the playground page.
The playground can be used to test your API call and also retrieve the API call URLs.
Step 1 is used to retrieve the authorization code.
Select your QuickBooks API app.
Select Accounting as the OAuth scope.
Click the Get Authorization Code button.
Step 2 is used to retrieve the OAuth tokens, so click the Get tokens button.
Step 3 is used to retrieve the API call URL, so click the Get your company button to display the API Calls request panel, populated with the Base URL and the request URL.
The Base URL (1) and the Request URL (2) are applied when you set up the endpoint test later in the tutorial.
Gather QuickBooks OAuth Server and Token URLs
Open the QuickBooks API documentation and scroll down to the following paragraph:
Copy the QuickBooks login URL
https://appcenter.intuit.com/connect/oauth2(without the query string parameters) and paste it into the OAuth Provider URL field in your Synatic OAuth connection.Also, copy the Scope URL you selected earlier,
com.intuit.quickbooks.accountingand add it to the Scopes section in your Synatic OAuth connection.
Now go back to the QuickBooks API documentation, and scroll down to the following paragraph:
Copy the QuickBooks token URL
https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
(without the query string parameters) and paste it into the OAuth Token URL field in your Synatic OAuth connection.
Getting an Authentication Token
Now that we've set up both Synatic and QuickBooks, we can execute the login flow to get an OAuth access token from QuickBooks.
In Synatic, click on the link Logon to oAuth Service.
A panel will open on the right-side of the screen. Click on the Logon to Service option to redirect to QuickBooks and authenticate Synatic.
If the Login is successful and Synatic has received the access token, you will see the notification below.
In the OAuth Connection in Synatic, the Auth Token field shows the access token placeholder as redacted.
Click OK to acknowledge the successful connection. The OAuth connection is now assigned the access token for each future occasion that you execute the flow. Click Save to finish setting up your connection.
Setup the HTTP Service step with a test endpoint
Now that we have a successful connection to QuickBooks, we can set up the endpoint to call. We're going to use a simple test endpoint, https://sandbox-quickbooks.api.intuit.com/v3/company/4620816365162546440/companyinfo/4620816365162546440 which gets the QuickBooks Company information of the user connected to the OAuth token.
Fill in the test endpoint in the URL field in the HTTP Service Step configuration:
Concatenate the Base URL and the Request URL.
1 -https://sandbox-quickbooks.api.intuit.com
2 -/v3/company/4620816365162546440/companyinfo/4620816365162546440Paste it into the Synatic HTTP Service URL step.
In the Headers section, add the Accept header with a value of "application/json" to instruct QuickBooks to process JSON content.
Click Save Step to finish up and return to the flow editor.
Test the Connection
As usual, it's always a good idea to test the Flow logic before continuing, so let's open the Synatic Flow designer again.
Click the blue Run Test play button on the Flow to run a simulation.
Then click Test to execute the API request.
Check the response to verify that the request was successful.
Things to try
Try accessing other QuickBooks endpoints to get other information from your account.
Try replicating this tutorial with another OAuth API, such as Google.
Read the Facebook OAuth2 tutorial.