Some of our APIs require authorization before you can use them. This is done via either of two methods: user authentication via login (using your regular account credentials) that generates an access token using the OAuth 2.0 methodology or a server authorization via an API key (created and retrieved beforehand via the LiveEngage UI) which uses the OAuth 1.0 methodology. Every API uses either of the two methods (or both), as listed in its overview (for example, the Users API).
What follows is a general overview of these two authorization methods and how they work, alongside other methods of authentication/authorization which occur in the LiveEngage platform (like consumer authentication for identification purposes and messaging conversation continuity).
Authorize API Calls
Login to LiveEngage Using Authentication (OAuth 2.0)
LiveEngage users can be agents, agent managers, campaign managers, and administrators. Using the Login Service API, you can log in one of these users to LiveEngage. Once you've logged in a user, you will receive back an authorization token (bearer). Use this token in your authorization header in all following API requests.
Note: that in order to use the Login Service API, you must first retrieve the service API domain which corresponds with the server that your account is on. For example, for the Users API, you'll need to make a GET request to the following endpoint:
Server Authorization (OAuth 1.0)
This method of authorization uses API keys pre-generated by an administrator on your account through the LiveEngage UI. For more information on how to create and retrieve these keys, please see this document.
Authorizing LiveEngage Applications
LiveEngage Applications are a code layer developed on top of LiveEngage APIs which include an
App_Install_Id parameter. This parameter is received when registering a dedicated configuration manifest that defines its scope and components. For more information on LiveEngage Applications, please refer to this document.
Sometimes, your application will need to make API calls on behalf of its user. In order to do so, it needs to be authorized just like we authorized other users above. In order to accomplish this, you will need to implement the LiveEngage Applications Authorization API (which uses the OAuth 2.0 methodology as explained above). This process requires multi-step token management. More information on how to do that can be found here.
Messaging Consumer Authentication and Identification
In order to provide consumers with a personalized experience where all their conversation history and metadata is continuous, uniform and accessible across multiple channels, brands need to authenticate each consumer with LiveEngage by passing PII (Personally identifiable information) from your IDP to LiveEngage. In order to make sure that consumers which won't be authenticated by the brand (i.e, the brand did not implement a connection with the IDP by choice) will still be able to start messaging conversations, the brand will need to configure an unauthenticated connector with LiveEngage (where LiveEngage provides a randomized token for each consumer, effectively enabling anonymous consumers).
Authentication occurs when the brand's IDP provides unique information on each consumer to LiveEngage via the standard OpenID Connect JWT method. The advantage of this is that LiveEngage is then able to display consumer information provided by the brand's IDP to the brand's agents under the OAuth 2.0 and OpenID connect protocols, providing a high degree of security and certainty regarding the consumer's identity. (for more details on what information is available from the IDP, please review the Personal Info engagement attribute and the Customer Info engagement attribute).
The authentication process occurs when the consumer opens the conversation window by interacting with an engagement. Because of this, every engagement is defined as authenticated or unauthenticated (that is, anonymous) through the LiveEngage UI, when creating a campaign. In order for unauthenticated engagements to work, contact your LivePerson account team who will need to enable the feature on your account. In order for authenticated conversations to work, the following several parameters need to be defined in by the brand's administrator in the brand's LiveEngage account. In order to define these parameters, follow these steps:
In LiveEngage, select Campaigns.
In the footnote, select Data Sources.
- In the Connectors area, next to the authentication server, click Configure. The Authentication Server page is displayed.
- From the dropdown menu, select your preferred authentication method, and complete the required fields.
In the Authentication Server, you will need to configure the following parameters:
Implicit or Code Flow
OAuth 2.0 Authentication Endpoint (when a separate browser window is used)
OAuth 2.0 Token Endpoint (when Code Flow is used)
OAuth 2.0 JWT Public Key
OAuth 2.0 Client ID
OAuth 2.0 Client Secret (when Code Flow is used)
JS method name and context (when LiveEngage embedded window is used in Web)
Additional information regarding authentication configuration in LiveEngage (including Implicit vs. Code Flow) is available here.