Authorization

The Lightspeed Retail (X-Series) API allows 2 methods of authorization:

• OAuth 2.0 standard as documented here: https://tools.ietf.org/html/rfc6749.
• Personal tokens which are a simple authorization method useful for headless scripts and other applications where OAuth is not suitable.

OAuth 2.0

Currently, we only support the Authorization Code Grant

Developer account and Lightspeed Retail (X-Series) application

Before starting, create a Lightspeed Retail (X-Series) application. To do this follow the steps below:

Step 1. Register as a developer

If you have not done this yet, register a developer account here.

NOTE: Your developer account credentials are independent of your Lightspeed Retail (X-Series) account so your existing Lightspeed Retail (X-Series) credentials will not work here.

Step 2. Create a Lightspeed Retail (X-Series) application

Once you sign in you will be redirected to the list of your Applications. Now you are ready to create your first app.

As a result, this process will give you the client_id and the client_secret which are used to identify your applications and are, therefore, required to complete the authorization process.

NOTE: redirect_uri is the address of your server which will accept the callback request from Lightspeed Retail (X-Series).

NOTE: You will notice that a newly created app is marked as Not Approved. Don’t worry! You can still use this app. Not Approved just means that you can only connect your application to 30 Lightspeed Retail (X-Series) stores. This should be more than enough for private apps or testing/staging environments. You only need to get our approval for production ready, public applications.

Connecting your application to a Lightspeed Retail (X-Series) Retailer Account

Implement the following steps to connect your application to a Lightspeed Retail (X-Series) Retailer account:

Step 1. Requesting authorization code

The Retailer (resource owner) needs to authorize your application to access their data. Send them to the following URL so that they can authorize your application.

https://secure.retail.lightspeed.app/connect?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}

NOTE: The redirect_uri must be exactly the same as what is registered for the app in your developer dashboard.

Once the Retailer has authorized the application, Lightspeed Retail (X-Series) will send an authorization code and the Retailer’s domain prefix to the Redirect URI you set up with your application.

Successful authorization response:

{redirect_uri}?code={code}&domain_prefix={domain_prefix}&state={state}&scope={scope}

Declined access response:

{redirect_uri}?error=access_denied

NOTE: The state parameter is a unique, randomly generated, opaque, and non-guessable string that allows you to bind the callback with a particular authorization request.
Checking the state parameter received in the callback matches the one your application sent in the authorization request, is essential to prevent Cross-Site Request Forgery attacks.
The state parameter is required, and it must be at least 8 characters long.

NOTE: The redirect_uri parameter should be defined exactly as it was when creating your application, without any additional parameters.

NOTE: Currently, the Lightspeed Retail (X-Series) API does not support scopes.

Step 2. Requesting an access token

Once you have the authorization code, your application can now request an access token and a refresh token.
The following data should be sent as “application/x-www-form-urlencoded” encoded body of a POST request.

NOTE: This data should not be sent as GET parameters in a query string.

• URL:

https://<<domain_prefix>>.retail.lightspeed.app/api/1.0/token

• Parameters:
  • code
  • client_id
  • client_secret
  • grant_type - this is always authorization_code
  • redirect_uri

NOTE: _The code is a short-lived (10 minutes), single-use value. Based on that assumption, every new authorization request should start with Step 1._

• Response:

  JSON

  {
      "access_token": "fMYgxHEYtcyT8cvtvgi1Za5DRs4vArSyvydlnd9f",
      "token_type": "Bearer",
      "expires": 1387145621,
      "expires_in": 86400,
      "refresh_token": "J3F62YPIQdfJjJia1xJuaHp7NoQYtm9y0WadNBTh",
      "domain_prefix": "domain_prefix",
      "scope": ""
  }
  

NOTE: The expires value is an absolute timestamp in seconds since the Unix epoch time (1970-01-01T00:00:00Z). EpochConverter is a nice tool converting epoch timestamps to human dates.

NOTE: The expires_in value is a relative time duration in seconds since this response was created.

Step 3. Using the token to access the Lightspeed Retail (X-Series) API

Your application can use the received access token to interact with the Lightspeed Retail (X-Series) API on behalf of the Retailer by providing the access token in an Authorization header.

GET https://<<domain_prefix>>.retail.lightspeed.app/api/products/{id}

Authorization: Bearer fMYgxHEYtcyT8cvtvgi1Za5DRs4vArSyvydlnd9f

Step 4. Refreshing the access token

When the access token expires, your application can request a new access token using the refresh token received in Step 2.

https://<<domain_prefix>>.retail.lightspeed.app/api/1.0/token

• Parameters:

  • refresh_token
  • client_id
  • client_secret
  • grant_type - when refreshing tokens it should be refresh_token

• Response:

  JSON

  {
      "access_token": "KD7gspXvfAmOsspC65YDqqJQ6FcAYbRROc4zPIMZ",
      "token_type": "Bearer",
      "expires": 1387145621,
      "expires_in": 604800,
      "refresh_token": "J3F62YPIQdfJjJia1xJuaHp7NoQYtm9y0WadNBTh",
      "domain_prefix": "domain_prefix",
      "scope": ""
  }
  

NOTE: The response payload will include a new refresh token. You need to update your currently stored refresh token.

Rate limiting

The token endpoint https://<<domain_prefix>>.retail.lightspeed.app/api/1.0/token is rate limited independently of the rest of the API.

When does rate limiting affect my implementation?

When an access token is issued, the response will include the time at which the token will expire (expires property) and the number of seconds until that time (expires_in property).
That information should be used to determine when to request a new access token, either because the access token is about to expire or because it has already expired.
It's recommended to use the access token until it expires, and then request a new one.

An application should call the token endpoint during the initial authorization process (when the user authorizes the application) and then again every time an access token is expired.
If the application follows this pattern, it won't be affected by rate limiting.

If the application calls the token endpoint more frequently than necessary, it might be affected by rate limiting. In that case, the application will receive a 429 Too Many Requests response.

How to avoid rate limiting?

The best way to avoid being rate limited, is to follow the pattern described above.
On top of that, the API will return informational headers on every request to the token endpoint:

• X-RateLimit-Limit: the maximum number of requests that can be made during the current window.
• X-RateLimit-Remaining: the number of requests remaining in the current window.
• X-RateLimit-Reset: the time at which the current window will reset, in seconds since the Unix epoch time (1970-01-01T00:00:00Z).

Example:

X-Ratelimit-Limit: 10
X-Ratelimit-Remaining: 9
X-Ratelimit-Reset: 1701129425

NOTE: This is just an example, all of these values are subject to change

Personal Tokens

Personal Tokens are a simplified method of acquiring an access token, for those use cases where the OAuth flow will not work. Good examples of those are scripts running periodically in the background or desktop applications.

Personal Tokens can be created by admin users directly in the web application as described here.

Warning: Although personal tokens are associated with the user that created it, if the user resets their password, the tokens will not be deleted.

If the user suspects that someone has their password, then please ensure that all personal tokens assigned to that user are regenerated.

To use a Personal Token to authorize a request, it should be used just like an OAuth token - it should be attached to every request in the Authorization header:

Authorization: Bearer fMYgxHEYtcyT8cvtvgi1Za5DRs4vArSyvydlnd9f