How to connect Integromat with any web service using OAuth2

One of many great features of Integromat is the ability to connect almost any web service to a scenario. In the following guide, I will show you with the help of a real example that even such a thing as communication with API can be handled without writing a single line of code.

As the illustrative example, I will integrate the DeviantArt service, one of the largest networks for creative people. My goal is to get a list of the latest deviations. Before I can configure the scenario, I first have to find out some basic information about the service. My first step will be to go through the Development section and find out what method DevianArt uses for user authentication, and which API is appropriate to perform the desired function.

Integromat supports the following authorization types:

• OAuth2
• Basic Authorization
• API key

Getting ready

In the Authentication section you will learn that DeviantArt uses a standardized OAuth2 protocol for authorization. At the same time you will find out that you must first create a so called client to be able to communicate with the API. To do that, click the register your application link. This will open up a form that allows to create a new application. Fill in the name and description of the application and upload the icon.

Next follows the Application settings section in which you need to fill out the OAuth2 Redirect URI Whitelis* field. All services that use standard OAuth2 protocol for authorization require this parameter. The value of this parameter is always the same — https://www.integromat.com/oauth/cb/oauth2. This is the URL, to which a user is redirected after they authorize Integromat to access the given service. This way, Integromat learns that the authorization has been successful, and creates a new connection with the service.

Once you have completed the registration, you will be taken to a screen where you can view two important values — client_id and client_secret. Write down these two values, you will need them later on.

Now go back to the Authentication section and find out three important pieces of information — authorization URL, access token URL, and information whether the service uses a refresh token to get a new access token. All services that use standard authorization OAuth2 protocol always indicate both URL addresses in the documentation. Renewing access tokens via a refresh token is optional, and if there is no mention about the refresh token in the documentation, the service does not support.

Now I have all important information about authorization so I can go on to the section APIS which describes in detail all API calls. The API that suits my purpose is located at GET /browse/newest. Expand the Authentication and Parameters sections, from which you can then learn what scope is required to call this API and what parameters you can send together with the request.

Creating a scenario

Now, go to Integromat and create a new scenario.

Before you start setting up your scenario in Integromat, I recommend you to go through all APIs that you plan to call and get a list of all scopes that are needed. You can then require all necessary scopes at once and avoid the hassle of expanding the scopes in the future.

Choose the OAuth 2.0 HTTP(S) request and response processing module from the HTTP package and add it to your scenario. In the open configuration window, click the Add button. This will bring up a window allowing to add a new OAuth2 connection. In this step, you enter the information that you have found in the documentation.

• Connection name — Enter any name you like to identify the connection.
• Authorize URI — the Authorize URL specified in the Authentication section of the DeviantArt documentation.
• Token URI — the Access Token URL indicated in the Authentication section of the DeviantArt documentation.
• Validate Access Token with Refresh Token — Enable this option (the DeviantArt documentation mentions that authorization uses refresh tokens).
• Scope — Specify the list of access scope that you want to grant to Integromat and associate with this connection. In my case, it is enough to select the browse value.
• Client ID — the client ID you were assigned once you have created the application.
• Client Secret — the secret key you were assigned once you have created the application.

After you click the Create a connection button, Integromat will try to establish the connection. If you have filled in the correct information, a window will be shown after a few seconds, in which you can authorize Integromat to access the given service via the application you have created.

After you grant consent, the access tokens will be exchanged in the background automatically. If everything is okay, the configuration window will be automatically populated with the newly created connection. Set up the URL address of the API endpoint according to the specifications given in the API documentation and specify optional parameters (in mycase, I will enter https://www.deviantart.com/api/v1/oauth2/browse/newest). When creating a scenario, it is always better to work with a smaller number of bundles. I will therefore add the limit=5 parameter to the end of the URL.

Testing

The integration is now ready and you can run the scenario. The execution results show that the call has been terminated with a 200 status, which means that the run completed successfully. The response details contain complete JSON data that is available for further use. In order to use this data in your scenario, you first need to parse it. That’s what the Parse JSON module from the JSON package is for. Before you add this module to your scenario, copy the whole json response to the system clipboard — you’ll need it in order to generate a data structure. Thanks to the data structures, Integromat knows exactly what structure the received data has.

Add the Parse JSON module to your scenario. In the settings of the module, map the Data variable from the HTTP package to the JSON string field. Next to the Data structure field, click the Add button and in the panel that opens, choose Generator. In the data structure generator, choose the JSON value as Content type and in the Sample data field paste the JSON response from the server that you have copied to the system clipboard. Once you confirm your entries, the data structure will be generated automatically. Give a name to the Data structure and click the Save button. The configuration of the Parse JSON module is now complete. Click the Save button to confirm the settings.

Run the scenario. Once the scenario run is complete, view details of the JSON module run. If everything has been processed without errors, you will see a list of 5 newest DeviantArt deviations. You can then easily browse through the data structure and map obtained values to other modules.

Originally published at www.integromat.com.