Authorization

Authorization

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

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.vendhq.com/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}

Declined access response:

{redirect_uri}?error=access_denied

NOTE: The state parameter can be used to pass some arbitrary data, allowing you to bind the callback with a particular authorization request.

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}.vendhq.com/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:

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

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. Currently, tokens expire in 24hrs.

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://someprefix.vendhq.com/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://someprefix.vendhq.com/api/1.0/token

  • Parameters:

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

  • Response:

    {
    "access_token": "KD7gspXvfAmOsspC65YDqqJQ6FcAYbRROc4zPIMZ",
    "token_type": "Bearer",
    "expires": 1387145621,
    "expires_in": 604800
}

NOTE: The response payload may include a refresh token. If so, you need to update your currently stored refresh token. If no refresh token exists in the payload, you can assume the refresh token was not rotated, and you can continue to use the original refresh token.

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: Personal tokens are associated with the user that created it. If the user resets their password, the tokens associated with that user will be deleted.

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