Configuring REST API connectors - API Key

When building your applications you would often be making use of a variety of services like Trello, Twilio, SendGrid, etc. 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 resources without a password.

Let us now understand how to connect to any API using an API key. One of the advantages of using API key authentication is its inherent simplicity. It’s a single key that allows you to authenticate just by including the key. Most commonly these connectors using API keys are used for read-only data. For APIs that don’t need write permissions, this is especially useful, while limiting risk.

Let us have a quick look at this video for brief introduction to the Authenticating REST API connectors using API key.

Let us now understand the process of configuring REST API Connectors using API Key authentication:

Configuring the third party API connector

Studio provides different Connectors to connect the Third-party. Let us take an example to connect SendGrid Mail. SendGrid API has API Key authentication so we will configure it accordingly.

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 API access to important 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 API Key authentication. So select API Key and click Continue.

Configure account-specific fields

Now you need to provide the parameters required to configure account-specific fields that are needed by the API for authentication or other purposes. The details are available in the documentation provided by respective 3rd party services. Thus depending upon fields required for each item like subdomain or team name you would define the parameter which would then have to be provided by the User when adding the Account for this service.

The configuration of the API Category is mainly to add the parameters that need to be provided for Authorization.

Under Step 1: Configure your fields > Add field

  1. Add the Label which is a user-friendly name for the users

  2. Add the field Key, which for this example would be Authorization. You can also make it a mandatory field.

  3. Now select the Type of field as Use String or Password. By default, it would be Use String. However, if you want the values to be secret or masked, then change the type as Password.

It is very important to select the Target where your API Key would be placed. It can be placed as Header, as Querystring Parameter, as Property inside Body or None. In case you set None then you need to specifically add this key in your api request using {{key_name}}.

target

Once these values are set you can Test the configuration using a Test API which is the details or values that you give.

Whenever you are trying to add an account this API will be called with requested keys (configured earlier). Now as this example is a simple GET API we are not adding any other parameter. Click Test to test your authentication scheme. You are now prompted to enter the API Key.

Here you can see the help text that we had given. Add the API in the format shown “Bearer api_key”. If you have marked it as a Password type it will be masked. Add the valid key and click Submit. So if the details are correctly provided your Test API responds with a success message. Now click Continue and the Connector is now added.

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 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. In this case you are choosing a POST method.

Under Configuration, there are Request, Response and Query String configurations. Add the Authentication details > select Account.

Under Request you can configure the Query string, the Headers, the Body, the Authentication settings, the Path Params and other Advanced configurations. You can also add a JSON Body for the API. You can have some parameters that can be dynamic in nature. These variables are placed in double curly brackets which are then shown below where you can provide the test value and default values. These parameters can be made dynamic and mandatory as required.

Note that in the Advanced tab you would get the dynamic parameters to which you can assign custom or user-friendly field names, preselect formula, as well as help text. The Preselect option can be used to have a dependent dropdown from another API.

Once you have configured the API as required, you can Test and Save. If you check the Response you would see the Status code depending upon success or failure of your Post method.

Your API can be seen under Custom API Connectors now. You can now see the API under Connectors > + Connector and view the parameters available. You can thus add API Connectors which have API Key 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.