Configuring REST API connectors - OAuth 2.0

When building your applications you would often be making use of a variety of services like Trello, Twilio, SendGrid, and so on that provide APIs to use their functionality. An important concern is to have ways and means to keep the systems secure. Authentication is an extremely crucial part of your API design. There are different methods of API authentication, using the API Key, using basic Auth which is using the username and password, and using the OAuth which is a standard for accessing user permissions without a password.

Studio has different options including the use of the REST API that allows you to easily connect to the Third Party API.access to important systems. Studio provides different Connectors to connect the Third-party. In scenarios where there are unrelated sites or services trying to accomplish actions on behalf of users. 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.

You can have quick look at the video to get a brief introduction to the connector authentication method.

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.

To configure an API you typically need to configure an API Category, Manage an Account and then add the API.

Configure API Category

You first need to provide the details of your API Category, thus enter a Category name and Category description. Add an appropriate icon and click Continue.

Now select the type of Authentication that you want to use. Here we are going to use the OAuth V2 authentication. So select OAuth V2 and click Continue.

To configure your API using OAuth v2, following are the typical steps:

  1. Configure your fields
  2. Copy the OAuth redirect URL
  3. Enter application credentials
  4. Add OAuth v2 Endpoint configuration

Now let us understand each of them:

Configure your fields

You can skip this step if the API does not require any details from the user who would be adding the account. You can provide the input fields for each item like sub-domain name that can be required for the Authentication or for creating an Endpoint. You can add a field in case there are any additional parameters required by the respective service. To understand how to add the new fields you can refer to the process which is similar to the one we used in the API key article.

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 secret from the app’s API or from the developer’s setting and paste them.

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.

    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.readwrite 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 : 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 and Close.

If you check the response it would return the response details as per your Test API endpoint.

Add account to the API configuration

The next thing is to add an account to the connector configuration. Click Manage Accounts to add as many accounts as required.

Make sure that you provide an account name and use the same steps used earlier to check the details.

Add API to configure

Now that you have configured the API category and added accounts you now need to add the API for configuration. Under Studio > Connectors > Custom API Connectors you can see your connector is added. To add this API, click Add API.

Now Add the Service Name, the Method and the URL to test your API. Under Authentication, add the Account that you created in the earlier steps.

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.

This will be shown under PATHPARAM, where you can assign the respective values. In this example we have added 0 (Zero) which indicates the root folder.

If you Test it now you, 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.

In case you want to view the contents of the folder in your App, you can add the respective folder’s folder_id under PATHPARAM.

So in this example we have copied the folder_id of the above folder DOC_Files.

The Response would include the list of files with its details as shown below. Now if you want to make it dynamic you can set the Dynamic toggle On. It is preferable to assign a user-friendly Field name and Help Text. In case you want to keep it Mandatory set the toggle ON.

Once you have configured the API as required, you can Test and 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 Custom API Connectors now. You can now see the API under Connectors > +Add API and view the parameters available. You can thus add API Connectors which have OAuth 2.0 as authentication.

These API 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.