Skip to main content

Overview

Introduction​

The Lightspeed Restaurant K-Series APIs support OAuth2 authentication using the authorization code grant flow. This article provides an overview of the authorization flow. For a step-by-step walkthrough, see our Authentication Tutorial.

The Authorization Flow​

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

1. Authorization Request​

An authorization request is made when a Lightspeed Restaurant POS user clicks on a URL provided by the integrator.

The 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.
important note

API Clients are bound to the server they were issued for. This means that if you have a client for the trial environment, it will not work on the production environment. Likewise, if you have a production client, it will not work on the trial environment.

If you need a new API client, please contact your Technical Partner Manager or Account Manager.

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.

Example Authorization URL​

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 will be 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.
  • The OAuth client will be granted the same access as the user who has approved the access. See About Access Tokens for more details.

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 re-initiate the Authorization flow.

Further Details​