Get AppJWT

LivePerson uses OAuth 2.0 grant type Client Credentials in order to allow apps to access the Send API. Sentinel, the responsible authorization server, generates access tokens for any rightfully authorized client. The access token is a Json Web Token (JWT) encoding information about the granted access and must be attached to any follow-up request to the Send API. However, the AppJWT alone is not sufficient to identify a consumer to Conversational Cloud. This means, one has to obtain a ConsumerJWS, too. The following HTTPS request exemplifies how to get an AppJWT:

POST /sentinel/api/account/{accId}/app/token?v=1.0&grant_type=client_credentials HTTP/1.1
Host: {sentinel_service_domain}
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}

The sentinel_service_domain can be retrieved using the LivePerson Domain API and searching for sentinel. The accId is your LivePerson site id. client_id and client_secret are given to you after application registration. The content type is always application/x-www-form-urlencoded. Sentinel will answer in accordance with OAuth 2.0. For example, a successful response looks as follows:

HTTP/1.1 200 OK
Date: Mon, 04 Nov 2019 16:00:47 GMT
Content-Type: application/json;charset=utf-8

{ "access_token": "eyJraWQiOiJhcHBqd3QtMTMtMDUtMTciLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJsZTgxODIzMTE4IiwiYXpwIjoiNzU1ODhlMTgtMDIxMy00ZTMzLTgxNzQtODgzYWNhYzdlM2M0Iiwic2NvcGUiOiJtc2cuY29uc3VtZXIiLCJpc3MiOiJTZW50aW5lbCIsImV4cCI6MTUyNDY0NjI3MCwiaWF0IjoxNTI0NjQyNjcwfQ.aC1EbVQDIKJkrMgfoqhDqo5KZVMILTGP5UnK_4lUJQIfpFcrymvQKU9E6zt_WDhWmM2SOOcr1sz4u5xVZ9rMWZciDW_9KofEM2NDgVw1EVBxAIgGYeO0sbE9o--HKjk9DHZvukJkQFhYaHMDnj6ay4BNUqTJpDn6y3XQY7eh7rM", "token_type": "Bearer" }

Decoding the access_token, using the Auth0 Debugger, reveals the following header and payload:

{
  "kid": "appjwt-13-05-17",
  "typ": "JWT",
  "alg": "RS256"
}

The kid (key id) is composed of appjwt and the date when it was issued. typ defines the type of the token. The type describes the content that is being signed or encrypted. The alg property defines the algorithm used to sign or encrypt the content. Here, the content is of type JWT which enforces the content to be structured according to the JWT standard. RS256 is a signing algorithm which ensures the data is not tampered. The payload looks as follows:

{
  "aud": "le81823118",
  "azp": "75588e18-0213-4e33-8174-883acac7e3c4",
  "scope": "msg.consumer",
  "iss": "Sentinel",
  "exp": 1524646270,
  "iat": 1524642670
}

Property aud defines the audience for whom the token is intended or the service for which it is intended. azp is the authorized party to which the AppJWT was issued. scope defines the part of application the authorized party has access to. iss defines the issuer of the token. exp is the expiration date and iat is the date when the token was issued. aud is always the account id, azp contains the app install id, scope is restricted to consumer, iss is sentinel and exp and iat contain the corresponding dates. An AppJWT is valid for one hour. For more information about JWTs, please also see this blog post.

Get ConsumerJWT

Getting Started

1. Retrieve your domain. Use the LivePerson Domain API to retrieve this information by providing the following service name:

   • idp

2. Note the API terms of use.

Authentication with ConsumerJWS

An AppJWT is not sufficient to identify a consumer with Conversational Cloud. With a valid AppJWT you can obtain a ConsumerJWS (JSON Web Signature):

The ConsumerJWS is the unique identifier of the user (consumer) and used by the connector in conjunction with the AppJWT to access Conversational Cloud on behalf of the consumer. Both the ConsumerJWS and the AppJWT will be passed in the headers of both the CONVERSATION and SEND requests to Conversational Cloud in order to authenticate the request.

A ConsumerJWS can be obtained with the following HTTPS request URI:

Path Parameters

Request Body Example — JSON Payload

{
	"ext_consumer_id":"John_Doe_facebook12345"
}

Query Parameter

Request Headers

Response

Response Codes

Response Example

{
    "token": "eyJraWQiOiJhcHBqd3QtMTMtMDUtMTciLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhY2NvdW50X2lkIjoibGUzMTQ1Nzc4MCIsImV4dF9jb25zdW1lcl9pZCI6InJhbmRvbV9pZDAuMTczMDc3OTY4NzUiLCJscF9jb25zdW1lcl9pZCI6IjI5Y2FmMGMxMTQ4Njk5NmQ5Mzg3ZTNhNDRlYzM0MjI5ZDEyNzMwNGRiNDk2NmQ3NzUyNzE2YmNlYjUzOGZhMjQifQ.TAJgP31rmpHvGKqb_yLP9yzVi_7tu7YoRfoqQ3RfuXGwR_AOV7DWL5Njy1m2YpC5kd9L_oRmytjFwfckwyuFJewwPGYxeZAY1q1jR5tPdb0nsvRyrMdKzO1_AFWUJtD013H9fjyjxHvxwV_Q2xe6Xp00J0T_-I6d6BkUpUFSPww"
}

Error Responses

The SEND API returns an error response for every authorization or authentication failure. Such an error response contains a JSON payload which details the error, error title, details about the error and both an HTTP error code (401) and a specific code for the type of error encountered. For example, if the AppJWT is missing, then the Send API will return the following response:

{
  "kind": "resp",
  "code": 401,
  "body": {
    "title": "AppJWT is missing",
    "details": "AUTHORIZATION header is not present",
    "errorCode": 40104
  },
  "type": ".ReqBody$ErrorResp"
}

Response Bodies

Each line in the following table represents one possible response body, including its title, details and errorCode. This means that there are five different error responses in total which can be returned by the API.