Skip to main content

Overview

The Lightspeed Restaurant K-Series APIs support OAuth2 authentication using the authorization code grant flow.

The Authorization Flow​

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

1. Authorization Request​

In a browser window, the end user is directed to the Lightspeed authorization URL.

Authorization URL​

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

  • The trial environment is used for development and testing of your application
  • The production environment is used to connect your app to live merchant accounts.
EnvironmentAuthorization URL
Trialhttps://api.trial.lsk.lightspeed.app/oauth/authorize
Productionhttps://api.lsk.lightspeed.app/oauth/authorize

The following query parameters must be passed in the Authorization URL:

  • response_type (required) - Must be code for the authorization code grant.
  • client_id (required) - The unique identifier for 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.

To connect to a merchant account on production, copy the following URL and replace the query parameter values with your own client ID, redirect URI, and scope(s). A state parameter can also be included, if desired.

https://api.lsk.lightspeed.app/oauth/authorize?response_type=code&client_id=DocumentationDemo-5745-4d30-8f1a-bd64511a62ed&redirect_uri=https://lightspeedhq.com/oauth-test.php&scope=financial-api%20orders-api&state=abcd123-efgh456

This URL should be supplied to the Lightspeed merchant to initiate the authorization request

  • 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.

OAuth2 Approval Form

2. Token Request​

Once the user authorizes the application, a temporary authorization code is passed to your redirect URI as a query parameter. If the state parameter was supplied, it will also be included.

It will look something like this:

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

The authorization code should be captured from the query parameter in the URL.

The code should then be exchanged for an access and refresh token pair by sending a POST request to the Token URL.

EnvironmentToken URL
Trialhttps://api.trial.lsk.lightspeed.app/oauth/token
Productionhttps://api.lsk.lightspeed.app/oauth/token

The client ID and client secret must be base64 encoded and passed as the authorization header in the following format client_id:client_secret.

For example:

DocumentationDemo-5745-4d30-8f1a-bd64511a62ed:fake-client-secret

becomes:

RG9jdW1lbnRhdGlvbkRlbW8tNTc0NS00ZDMwLThmMWEtYmQ2NDUxMWE2MmVkOmZha2UtY2xpZW50LXNlY3JldA==

The following values must be passed as query parameters:

  • grant_type=authorization_code
  • code=GyIpgM (replace with the code returned in redirect URL query parameter)
  • redirect_uri=https://your_redirect_uri (replace with the redirect URI 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://your_redirect_uri'

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 values must be passed in the request body as an x-www-form-encoded payload. The endpoint will return a new access token and a new refresh token.

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 "
}
NOTE

Refresh tokens remain valid for 14 days. If you do not refresh your access token within 14 days, you will need to reinitiate the Authorization flow.

Further Details​