Configuring REST API connectors - OAuth 2.0

Studio provides you with several Connectors like Databases like MySQL, Microsoft SQL, etc., and Third-party connectors like Slack, Trello, Stripe, etc. You can connect the different APIs using their respective authentication methods. There are different methods of API authentication, using the API Key, using basic Auth which is using the username and password, using the OAuth which is a standard for accessing user permissions without a password, and the AWS authentication method.

OAuth 2.0 is about authorization. The implementation returns an access token that would be used with the DronaHQ integration to authorize requests. It is a protocol that allows the user to grant a third-party website or application access to the user’s protected resources without revealing the identity of the user. It is an open standard followed by several major third-party services.

Configuring the API connector

To add third-party connectors, under Studio > Connectors, click (+) Connector.

Studio has different options including the use of the REST API that allows you to easily connect to the Third Party APIs to access the systems. We will be selecting the REST API for this example.

Configure API Category

When configuring the APIs you need to provide the Authentication details for the respective authentication method. Let us first see how to configure an API using the OAuth V2 authentication method. Let us consider an example to add the BOX API which uses the OAuth V2 authentication.

  • Once you select the option as REST API, enter the Connector name which should ideally be self-explanatory.

  • Select the Authentication method as OAuth V2.

    To configure your API category using OAuth V2 authentication, you need to enter the following details.

  • Copy the OAuth redirect URL: You need to copy the URL link provided in this step. It would be used in the respective developer portal of the service’s client application that will receive OAuth 2.0 credentials. Once you create the client app in the service you need to copy this URL to the section usually marked as OAuth 2.0 redirect URI of the app. You can also add additional permissions if required for the application. You can also add the redirect URL in the allowed origin section as well.

  • Enter the application credentials:
    You need to configure the application credentials. Simply copy the Client Id and Client Secret from the app’s API or from the developer’s setting and paste them in the connector configuration.

  • Add OAuth v2 Endpoint configuration: The last step is to add the Authorization URL required for your API. You would specify where to send users to authenticate with your API.

    You need to provide the following details:

    • Authorization URL : specifies where the users are sent to authenticate with your API. If you go to the Development portal, you will see the authorization user URL. Copy it from the portal and paste it to the Authorize URL. Usually when you add the URL from your API no further settings are required. However, some API may need further customization which includes the parameters response type, client id and so on. These are the Advance options available in your configuration.

      If you note the parameters, the response_type returns authorization code, client_id will be retrieved with {{auth.client_id}} scope is the permissions that we want to add. The Scope can be added in the next field Scope like root.read-write and manage.app_users. This will be used in parameters using {{auth. scope}}. After the authorization URL is called, once the user approves the sign-in request you are redirected to the Callback URL from where the AccessToken API will be called. So now you need to get the AccessToken API Endpoint from the portal.

    • Access Token Request: It specifies the endpoint URL where Studio sends the approval code. It is sent through POST method type and receives the access_token in the response.

    • Refresh token request : You can also request a refreshed access token using Refresh Token Request when a 401 UnAuthorized Error is thrown.

  • Once these configurations are done, you need to Test request and connection.

    If the authentication is successful you would get the response accordingly that the configuration is verified then Save.

You now have the respective API configured which can then be used further.

Add API

You can now add APIs based on the Connector configuration. Under Studio > Connectors you can see your connector is added. To add your new API as per the API endpoint, click Add API.

Now Add the Connector API name and the API endpoint with the required parameters and test your API.

Now in the URL for the sake of this example, we are going to retrieve the folder and file details. You can note that we have assigned a folder_id parameter. This is the dynamic variable that would be used to assign the folder_id for the folder you are accessing from your BOX app.

If you Test it now, you can view the Response as shown below on successful authentication. For this example, there is a DOC_files folder that was created in your BOX app.

For the root folder_id, the response shows the details for the respective folders in the location.

Once you have configured the API as required, you can Test API and then if successful, click to Save. If you check the Response you would see the response for the respective folder id or the parameters provided.

Your API can be seen under respective Connectors now. You can thus add API Connectors that have OAuth 2.0 as authentication.

These APIs can be used in your Apps and workflows using the CALLAPI function. You can refer to this link here to understand how to use the API services.