Overview

The Lightspeed Restaurant K Series API allows third-party developers to build custom integrations to Lightspeed. To gain access to the API, the developer must first be approved by Lightspeed's Partnerships team.

OAuth2 Authorzation

The K Series APIs support OAuth2 authentication using the authorization code grant flow. To request an OAuth client and gain access to the API, please contact the Partnerships team.

Quick Facts

• Access tokens expire after 60 minutes
• Refresh tokens do not expire
• Refresh tokens can only be used one time
• Redirect URLs require HTTPS

Endpoints

Below are the URLs that should be used during the authorization process.

Authorization Overview

Obtaining an access token using the OAuth2 authorization code grant flow consists of three steps:

1. Authorization Request

• In a browser window, the end user is directed to the Lightspeed authorization URL (see Endpoints table)
• The following query parameters must be passed in the URL:
  • response_type (required) - must be code for the authorization code grant
  • client_id (required) - the unique identifier of the OAuth client
  • scope (required) - the access scopes being requested, space delimited (URL encoded)
  • redirect_uri (required) - the URL that the user will be redirected to after authenticating and authorizing the integration
  • state (optional) - a unique string supplied by the external client that is persisted throughout the process to track the request

https://api.lsk.lightspeed.app/oauth/authorize
?response_type=code
&client_id=Documentation%20Demo
&redirect_uri=https://lightspeedhq.com/oauth-test.php
&scope=financial-api%20orders-api
&state=abcd123-efgh456

• The user is prompted to login to Lightspeed. Upon successful login, the user must provide consent for the OAuth client to access their data
• Each scope must be individually approved by the user

• Upon successfully providing consent authenticating, the user is redirected to the redirect URL associated with the OAuth client

2. Token Request

• A temporary authorization code is passed as a query parameter when the redirect URL is called. If the state parameter was supplied, it will also be included.

https://your-redirect-url
?code=GyIpgM
&state=abcd123-efgh456

• The authorization code is captured from the query parameter in the URL. The code is then exchanged for an access and refresh token pair by sending a POST request to the /token endpoint
• The client ID and client secret must be base64 encoded and passed as the authorization header in the following format client_id:client_secret
• The following values must be passed as query parameters:
  • grant_type=authorization_code
  • code=abc123 (replace with the code returned in redirect URL query parameter)
  • redirect_uri=https://your_redirect_url (replace with the redirect URL for the client)

Sample Request:

curl \
--header 'Authorization: Basic c29tZV9jbGllbnRfaWQ6c29tZV9jbGllbnRfc2VjcmV0MQ==' \
--request POST 'https://api.lsk.lightspeed.app/oauth/token?grant_type=authorization_code&code=Bp68Nr&redirect_uri=https://lsapi.pw/resto/lsk-prod.php'

Sample Response:

{
  "access_token": "5f7fe870-fa7c-4b27-a892-2caebabb9bda",
  "token_type": "bearer",
  "refresh_token": "138fc571-68b0-426d-82d3-b6386421788c",
  "expires_in": 3599,
  "scope": "financial-api orders-api "
}

3. Refreshing the Token

• Refresh tokens can be exchanged for a new access and refresh token pair by sending a POST request to the /token endpoint
• The client ID and client secret must be base64 encoded and passed as the authorization header in the following format client_id:client_secret
• The following values must be passed in the request body as an x-www-form-encoded payload:
  • grant_type=refresh_token
  • refresh_token=abc123 (replace with refresh token value returned in step 2)

Sample Request:

curl \
--header 'Authorization: Basic c29tZV9jbGllbnRfaWQ6c29tZV9jbGllbnRfc2VjcmV0MQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=138fc571-68b0-426d-82d3-b6386421788c' \
--request POST 'https://api.lsk.lightspeed.app/oauth/token'

Sample Response:

{
  "access_token": "4543e601-144d-484a-8d1f-5110e9c603ca",
  "token_type": "bearer",
  "refresh_token": "f0e0083a-e08d-4be7-8d66-0d6440cb71c4",
  "expires_in": 3599,
  "scope": "financial-api orders-api "
}

Access Scopes

OAuth clients are limited to the specific access scopes required by the integration. During the authorization process, only scopes that have been added to the OAuth client may be requested. See the below table for the full list of access scopes.