What are the various ways to validate API keys in the iparams page?

What are the various ways to validate Product API key in the iparams?

Be it any Freshworks product, in order to access the REST APIs, an API Key is required. It can be obtained either manually (Refer API doc - Authentication section) or automatically (Refer SDK doc - Installation parameters,data-bind feature) depending on the product.

Regardless, it needs to be validated prior to usage. There are few ways to validate the product key depending on the scenario:

  • Standard iparams.json: Using domain & api_key iparam fields
  • Dynamic iparams.json: Using Callback validation & Request API
  • Custom iparams.html, json: Using Server Method Invocation (SMI)

Standard iparams.json : Using domain & api_key iparam fields

This is a simple and recommended approach to obtain the api_key value. In the iparams.json, one can include a pair of domain and api_key for a particular product (should be marketplace-enabled) like so:

{
  "fd_domain": {
    "display_name": "Account",
    "description": "Please enter your Freshdesk sub-domain",
    "type": "domain",
    "required": true,
    "type_attributes": {
      "product": "freshdesk"
    }
  },
  "fd_api_key": {
    "display_name": "API Key",
    "description": "Please enter your API key",
    "type": "api_key",
    "required": true,
    "type_attributes": {
      "product": "freshdesk"
    },
    "secure": true
  }
}

Based on the value of type_attributes.product, not only is the styling taken care, the validation is also done accordingly!

Dynamic iparams.json : Using callback validation

Iparams.json also offers a way to attach a callback function to a particular field. When the value changes, the associated callback function will be triggered. For instance, consider an iparams.json file like so

{
  "fd_domain": {
    "display_name": "Account",
    "description": "Please enter your Freshdesk sub-domain",
    "type": "text",
    "required": true
  },
  "fd_api_key": {
    "display_name": "API Key",
    "description": "Please enter your API key",
    "type": "text",
    "events": [{
      "change": "validateKey"
    }],
    "required": true,
    "secure": true
  }
}

Notice the presence of events property in the second iparam. Basically, we register a change event handler to listen to field value changes. A corresponding callback with the name validateKey should be present in config/assets/iparams.js file of your app. It might look like the following snippet

/* global app,client, utils */
var timeout;
/**
 * App lifecycle method to initialize the app and to obtain the `client` object
 * More details on Dynamic Installation parameters can be found at the link below ⬇️
 * https://developers.freshdesk.com/v2/docs/installation-parameters/#dynamic_install_page
 */
app.initialized().then(
  function (_client) {
    window.client = _client;
  },
  function (error) {
    //If unsuccessful
    console.error(error);
  }
);

/**
 * Payload and other options can be specified using `options`
 * Notice the presence of the debounce logic to avoid rate-limiting issues
 * 
 * @param {string} value 
 */
function validateKey(value) {
  //Assume it is the validation/resource endpoint
  var url = "https://" + utils.get("fd_domain") + ".freshdesk.com/api/v2/settings/helpdesk";
  var options = {
    headers: {
      Authorization: btoa(value + ":X")
    }
  };
  var p = new Promise(function (resolve, reject) {
    // Do not hit the validation API immediately upon change
    // Wait for 500ms and if the user hasn't typed anything during that time, make a call
    clearTimeout(timeout);
    timeout = setTimeout(function () {
      client.request.get(url, options).then(
        function (data) {
          // Upon success, just resolve
          resolve();
        },
        function (error) {
          // Upon failure - send an appropriate validation error message
          reject("This key is invalid. Please enter the right one");
        }
      );
    }, 500);
  });
  return p;
}

As you can notice, the callback returns a promise which resolves based on the status of the Request API call. This method can be used in scenarios where you would like to use standard iparams.json with custom validation for a product that is not marketplace-enabled or a third-party product.

image

Custom Iparams.html: Using Server Method Invocation (SMI)

SMI & Request API calls are possible from the Installation pages. In the case of SMI, one can delegate the validation to an SMI method and simply pass the encoded parameters from the install pages. Based on the values returned by renderData, the validation status can be determined. One can also make direct use of Request API to validate API keys.

For reference:
https://developers.freshdesk.com/v2/docs/server-method-invocation
https://developers.freshdesk.com/v2/docs/request-api

5 Likes

3 posts were merged into an existing topic: Auto-Fill Sub-Domain & API Key on Install Page