Invoking Lapp APIs

Authentication Models

There are 3 authentication models available with Lapp in order to call Lapp API securely. These are described below –

​​​​​​​With the x-api-key in the Header

The most secure and suggested mode to call a Lapp API is by passing the x-api-key in the request header. The x-api-key is displayed when you publish/republish a Lapp. Few important points about the x-api-key are –

  • Lapp with x-api-key in the header can be called as any REST API from any origin/domain/3rd party system
  • x-api-key is common for all the Lapps of the tenant. If it’s compromised, one can call any Lapp of the tenant.
  • Never call the Lapp API from a public domain with x-api-key in header. This exposes the x-api-key in plaint text to a user. For example, from a HTML page in making ajax request.
  • If a tenant is deactivated, the x-api-key becomes invalid. Upon reactivation, all existing Lapps will still be shown as published with the same x-api-key. However, you need to republish all Lapps in order to generate and associate new x-api-key. Also, note that any existing integration with Automation or Forms is required to be performed again.

 

Within LeadSquared Domain with no Special Authentication

It is often required to create custom HTML/single-page apps that are rendered in connectors like Custom Tab. As these web pages/scripts render inside the LeadSquared domain, we can securely call Lapp URL while the user is logged in.
​​​​​​​In order to create such compatible apps, a developer needs to follow the instructions mentioned below –

1. Add the following scripts in the head section of the HTML. This will expose the plugin to invoke Lapp API without any manual authentication.

<script type="text/javascript" src="https://developerapp.leadsquared.com/customapp/jquery.min.js" type="text/javascript"></script>
<script type="text/javascript" src="https://developerapp.leadsquared.com/customapp/script.js" type="text/javascript"></script>
<script>
lapp.initialize({
"region" : "mum" //one of mum/sgp/us
});
/*Alternate approach with default region as mumbai
lapp.initialize();
*/
</script>

 

Using x-api-key during development

The plugin requires the user to be logged into the tenant account all the time. If the developer wants to test and develop independent of being logged in, pass Lapp’s x-api-key in the initialize function

<script type="text/javascript" src="https://developerapp.leadsquared.com/customapp/jquery.min.js" type="text/javascript"></script>
<script type="text/javascript" src="https://developerapp.leadsquared.com/customapp/script.js" type="text/javascript"></script>
<script>
lapp.initialize({
"region" : "mum",
"xpikey" : "x-api-key value"
});
</script>

Note: Never use x-api-key in lapp.initialize for production. This exposes your account x-api-key in plain text to everyone, compromising all the Lapps of that tenant.

 

2. The plugin exposes lapp.invoke method that accepts four parameters

  1. ​​​​​​​​​​​​​​LappId – id of the Lapp e.g. da_9329_6f8ce269. The same can be found in the usual Lapp URL
  2. Environment – Test/Live
  3. Querystring – any additional querystring parameters separated by ‘&’ e.g. “source=web&category=sales”
  4. Body – post data as JSON object

Below is the signature of lapp.invoke method:

lapp.invoke("lappId", "Test", "source=web&category=sales", body)
.then((data) => {
// code on success
})
.catch((err) => {
// code on failure
})
​

Sample Code for In-Origin Lapp Access

Please find the sample code here – Lapps_SampleCodeForInDomainAuthentication.
It presents a simple HTML page that is expected to be used in a Custom Tab connector for the Lead details page. This page does the following:

  1. Expects LeadId in the querystring
  2. Calls Lapp to fetch lead details and capitalize first and last name of the lead.
  3. Show formatted first and last name in UI

 

Additional files for Custom App development

Lapp exposes following files for custom app development:

  1. JQuery(v3.5.1): https://developerapp.leadsquared.com/customapp/jquery.min.js
  2. Bootstrap JS(v4.0.0): https://developerapp.leadsquared.com/customapp/bootstrap/js/bootstrap.min.js
  3. Bootstrap CSS(v4.0.0): https://developerapp.leadsquared.com/customapp/bootstrap/css/bootstrap.min.css

 

With Lapp Public URL

Lapp can be configured to call with authentication token passed in the querystring. This token is generated individually for each Lapp when requested. the token is termed as xapikey in the querystring parameter.
The URL looks like: https://lapps-in21.leadsquared.com/executebylapptoken?name=<lappid>&stage=Live&xapikey=<lapptoken>
To generate a token for Lapp, open the API URL section in Lapp and click on Generate public Lapp API as shown below

Lapps

Note: xapikey should never be exposed in the browser directly via client-side script outside LeadSquared domain. Lapp APIs are always advised to be invoked from server side.
​​​​​​​In case it is absolute to invoke Lapp API from client-side outside LeadSquared domain or from 3rd party apps that does not support passing xapikey in the request header, always use public Lapp API that compromises only access to that particular Lapp.

 

API Behaviour Control with querystring Parameters

Lapp APIs supports the following querystring parameters –

async=1
Lapp API returns a response after it completes the entire execution. This is known as sync behaviour. In case one requires to just trigger the Lapp and return acknowledgement response immediately, async parameter can be used.

Following will be the Lapp response with async=1

{
"statusCode": 200,
"message": "your request has been successfully accepted"
}

excludemetainresponse=1
Lapp API returns the response with statusCode and message. message carries the object returned from the Lapp code. For example, suppose the response returned from Lapp code is {“Result” : “Function succeeded”}. The usual format of Lapp API response is shown below –

{
"statusCode": 200,
"message": {
"Result": "Function succeeded"
}
}
If you pass excludemetainresponse=1 then Lapp API will return the exact object returned by the Lapp code. The appropriate response for our example is shown below -

{
"Result": "Function succeeded"
}

excluderequestlog=1
Passing this param will ensure that the querystring params and body of the request are not logged by default for each Lapp API call. This is done as in some cases customer wants to hide that data intentionally for security reasons. Please note, that the code can still explicitly log the querystring and body, if required.