Skip to main content

Authentication Tutorial

Introduction​

The Lightspeed Restaurant K-Series APIs use OAuth2 to authenticate API users. This consists of four basic steps:

  • A Lightspeed Restaurant K-Series POS user authorizes the API Client to access the account.

  • A temporary authorization code is issued.

  • The temporary code is used to generate an access token and a refresh token.

  • Once the access token expires, the refresh token is used to generate a new access token.

Below you will find basic step by step instructions for retrieving an access token and using it to request data from the K-Series APIs. For more details, see Authorization Overview.

Before you begin

  • Set up a Postman workspace by following our Setting Up Postman tutorial.

  • Make sure you have an account on the demo server for testing. If you do not have a test account, please contact your Technical Partner Manager or Account Manager.

Part 1 - Generating an Access Token​

Step 1​

Generate a URL with the following format:

https://api.trial.lsk.lightspeed.app/oauth/authorize?client_id={{CLIENT_ID_HERE}}&response_type=code&redirect_uri={{REDIRECT_URI_HERE}}

Make sure your client_id and redirect_uri are correct.

This URL should be opened in a browser window. A sign in box will be displayed:

Step 1

Important Note

API Clients are created for either the Demo server or the Production server. Make sure your login credentials are for the same server as your API Client.

Step 2​

Log in, accept the access scope(s) requested for the client, and click 'Authorize'.

Step 2

A temporary code will be sent to the redirect URI with the authorization code in parameter, like this:

https://mycompany.com/redirect/kseries?code=VlWFo0

It will also be displayed in the browser address bar. Copy the code to your clipboard.

Step 3​

Open the POST Request Token request in your K-Series API Collection. Make sure you have the correct environment selected from the dropdown in the top right corner.

Step 3

Step 4​

Open the Params tab and paste in the temporary code.

The complete URL should now look like this:

https://api.trial.lsk.lightspeed.app/oauth/token?code={{TEMPORARY_CODE}}&grant_type=authorization_code&client-id={{YOUR_CLIENT_ID}}&redirect_uri={{YOUR_REDIRECT_URI}}
Good to know

When an environment is correctly set up in the K-Series Postman Collection, the request headers containing the required base64 encoded client credentials are automatically generated in the Authorization tab of the authentication requests

Good to Know

Step 5​

Click Send.

This request will return the access token and refresh token.

Step 4

Good to know

In the K-Series Postman Collection, the scripts saved in the 'Tests' tab of the POST Request Token request will automatically update the access token and refresh token in your environment.

Part 2 - Getting Business Details​

Your newly generated access token is associated with the user and account that authorized it. Your access token will have access to the same Business Locations as the user.

Both the Order & Payment and Financial APIs offer endpoints to retrieve the account details.

Step 1​

In the K-Series Postman Collection, open either the Order & Payment or Financial API's GET Business request.

Click 'Send'.

Step 6

Step 2​

The request will return the Business details, including all the Business Locations that the token grants access to. You can copy the desired businessLocationId to your environment to facilitate making Postman requests to the account. A Business can have multiple Business Locations. See Business Locations for more details.

Good to know

In the K-Series Postman Collection, the reference to the access_token environment variable is saved at the collection level in the 'Authorization' tab. This allows it to be applied across all requests in the collection.

Auth Tab

Part 3 - Refreshing the Access Token​

Access tokens expire after one hour. You will need to use the refresh token to generate a new access token.

Step 1​

Open the POST Request Token request in your K-Series API Collection. Make sure you have the correct environment selected from the dropdown in the top right corner.

Step 5

Step 2​

The refresh token should still be saved in your environment, so all you need to do is click 'Send' and a new access token and refresh token will be generated and saved to your environment.