Skip to main content

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=DocumentationDemo-5745-4d30-8f1a-bd64511a62ed&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

OAuth2 Approval Form

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=GyIpgM (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 "
}