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 Conversational Cloud 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 Conversational Cloud platform (like consumer authentication for identification purposes and messaging conversation continuity).

Authorize API Calls

Login to Conversational Cloud Using Authentication (OAuth 2.0)

Conversational Cloud users can be agents, agent managers, campaign managers, and administrators. Using the Login Service API, you can log in one of these users to Conversational Cloud. 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: 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:

https://api.liveperson.net/api/account/{accountId}/service/{serviceName}/baseURI.json?version=1.0

For more information on the Domain API and how to use it to retrieve your domain, please see the API itself. For more information on the Login Service API, please refer to its documentation.

Server Authorization (OAuth 1.0)

This method of authorization uses API keys pre-generated by an administrator on your account through the Conversational Cloud UI. For more information on how to create and retrieve these keys, please see this document.

Authorizing Conversational Cloud Applications

Conversational Cloud Applications are a code layer developed on top of Conversational Cloud 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 Conversational Cloud 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 Conversational Cloud 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 Conversational Cloud by passing PII (Personally identifiable information) from your IDP to Conversational Cloud. 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 Conversational Cloud (where Conversational Cloud 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 Conversational Cloud via the standard OpenID Connect JWT method. The advantage of this is that Conversational Cloud 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 Conversational Cloud 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 Conversational Cloud account. In order to define these parameters, follow these steps:

1. In Conversational Cloud, select Campaign Builder.

2. In the footnote, select Data Sources.

3. In the Connectors area, next to the authentication server, click Configure. The Authentication Server page is displayed.

4. 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 Conversational Cloud embedded window is used in Web)

Additional information regarding authentication configuration in Conversational Cloud (including Implicit vs. Code Flow) is available here.