Lighthouse Token Flow

Technical overview of the 3rd-party integration Lighthouse token process in Shift4 Marketplace.

Flow

The image below presents a simplified OAuth + Retrieve Locations Request Flow sequence diagram.

1. The merchant initiates a request to S4 LH Auth, providing its client ID, in order to obtain an authorization code.
2. Upon receiving the request, LH Auth redirects the merchant back to the specified redirect URI, appending a code query parameter containing the authorization code.
3. The merchant, having received the authorization code, proceeds to exchange it with S4 LH Auth in order to acquire an access token.
4. S4 LH Auth responds to the merchant's request by providing an access token, which can be used for subsequent API calls.
5. Using the obtained access token, the merchant makes a request to the Conecto API, specifically asking for a list of LH User Locations.
6. The Conecto API processes the request and returns a response containing the requested list of User Locations.

The image below presents a simplified activate Location Request Flow sequence diagram.

1. The Merchant sends a request to the S4 Conecto API, requesting the installation of an integration for a specific location. The request includes the LH User Access Token, which serves as an authorization credential.
2. Upon receiving the request, the S4 LH OAuth validates the provided Access token in the middleware of the Conecto API. This validation process ensures that the token is valid and authorized to access the requested resources.
3. After successful validation, the Conecto API proceeds to install the integration for the requested location. Once the installation is completed, the API sends a response with a status code of 204, indicating a successful operation without any content in the response body.

OAuth Authorization

Before Lighthouse merchants can use your application, they need to grant it permission to make API calls on their behalf. Use OAuth for this purpose.

Step 1: Initiating the OAuth flow

Once you establish both a client_id and a client_secret, you are ready to allow your customers to initiate the OAuth flow. Send them to URL with the following parameters:

/oauth2/authorize/?<PARAMETERS>

Authorization URL example

https://lighthouse-api.harbortouch.com/oauth2/authorize/?client_id=APP_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code

At this URL, the Merchant will see a log-in screen:

The permissions form is displayed when the Merchant signs in to Lighthouse:

The permissions form is displayed when the Merchant signs in to Lighthouse.

It shows which permissions the application is requesting. If the merchant is comfortable with the permissions listed, he clicks Allow. Otherwise, she clicks Deny.

In either case Merchant will be redirected back to your provided redirect_uri.

Step 2: Handling the redirect

Allow Case

Once the Merchant clicks Allow, they will be redirected back to your predefined redirect_uri with a code query parameter. The value of this parameter is an authorization code.

You can swap these parameters for a token by POST'ing to /oauth2/token/ with the JSON Object structure in request body as defined bellow.

Request:

POST /oauth2/token/

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "client_id": "APP_CLIENT_ID",
  "client_secret": "APP_CLIENT_SECRET"
}

Response:

The Access Token will be send as a JSON object.

{
  "access_token": "USER_ACCESS_TOKEN",
  "refresh_token": "USER_REFRESH_TOKEN",
  "permissions": [],
  "expiration": 14952189,
  "token_type": "Bearer"
}

Deny Case

If Merchant clicks Denied, they will be redirected back to your predefined redirect_uri with a error=access_denied query parameter.

Step 3: Renew your access token

Access Tokens expire in 24 hours. If you make a request to a Lighthouse API endpoint with an expired access token, you will get a 401 Unauthorized error.

You can renew an expired access token by POST'ing to /oauth2/token/ with the JSON Object structure in request body as described bellow.

Request:

POST /oauth2/token/

{
  "grant_type": "refresh_token",
  "refresh_token": "USER_REFRESH_TOKEN",
  "client_id": "APP_CLIENT_ID",
  "client_secret": "APP_CLIENT_SECRET"
}

Response:

The Access Token will be send as a JSON object.

{
  "access_token": "USER_ACCESS_TOKEN",
  "refresh_token": "USER_REFRESH_TOKEN",
  "permissions": [],
  "token_type": "Bearer"
}

Using the token

Send your access token with each api request in a header:

Below you will find curl command example:

curl -X GET https://lighthouse-api.harbortouch.com/api/v1/locations/ -H 'authorization: Bearer USER_ACCESS_TOKEN'

Conecto API

Retrieve lighthouse-token eligible locations for app installation

Retrieve a list of LH user locations that are eligible for 3rd party app installation

GET /marketplace/v2/lighthouse-token/locations

Response 200

Returns a collection of eligible locations

{
  "results": [
    {
      "isAvailable": true,
      "reason": "INSTALLED",
      "location": {
        "id": 0,
        "name": "string",
        "timeZone": "string",
        "merchantId": "string",
        "countryCode": "US",
        "currency": "USD",
        "language": "en",
        "brandRef": "string"
      },
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "string",
        "countryCode": "string",
        "postalCode": "string",
        "coordinates": {
          "latitude": "string",
          "longitude": "string"
        }
      }
    }
  ],
  "meta": {
    "count": 0
  }
}

POST /marketplace/v2/lighthouse-token/installations

POST /marketplace/v2/lighthouse-token/installations

Request Body (required)

Content-Type: application/json

{
  "locationId": 0
}

Response 204

Installation was successful

Models

• LocationData
• LocationAddress

LocationData

Location data

LocationAddress

Location address information