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-keyin the header can be called as any REST API from any origin/domain/3rd party system x-api-keyis 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-keyin header. This exposes thex-api-keyin plaint text to a user. For example, from a HTML page in making ajax request. - If a tenant is deactivated, the
x-api-keybecomes invalid. Upon reactivation, all existing Lapps will still be shown as published with the samex-api-key. However, you need to republish all Lapps in order to generate and associate newx-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
- LappId – id of the Lapp e.g. da_9329_6f8ce269. The same can be found in the usual Lapp URL
- Environment – Test/Live
- Querystring – any additional querystring parameters separated by ‘&’ e.g. “source=web&category=sales”
- 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:
- Expects
LeadIdin the querystring - Calls Lapp to fetch lead details and capitalize first and last name of the lead.
- Show formatted first and last name in UI
Additional files for Custom App development
Lapp exposes following files for custom app development:
- JQuery(v3.5.1): https://developerapp.leadsquared.com/customapp/jquery.min.js
- Bootstrap JS(v4.0.0): https://developerapp.leadsquared.com/customapp/bootstrap/js/bootstrap.min.js
- 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
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.
compressrequestbody=1
Passing this parameter will compress the request body posted with the Lapp call. This will allow users to support larger payloads. It compresses the payload to slightly over 1/4th the input, when the request passed internally through the system.
It’s useful to overcome the default payload size restriction when using async mode (async=1). In async mode, the max permitted size of the payload is 256KB. Using this parameter, almost 1MB of the request body payload is supported. It may be helpful for use cases where Automation calls are made to Lapp APIs.
Note: The request you’re passing to a Lapp cannot be more than 6MB in total. That is the hard upper limit.
