This guide is designed to provide further explanation on the process detailed in the Authentication page of our API Docs.
If you have not already created an integration, you will need to do so by following the steps here.
If you want to follow this guide step by step (say for example you do not yet have a working OAuth process on your server) you'll need a URL from https://webhook.site - these are free but be aware they are publicly accessible so only suitable for testing.
Building the Authentication URL
In the settings of your Integration you will find your Client ID, you should already have your Client Secret recorded somewhere.
Please also make note of your redirect URI on this page, it must match in the authorization URL that you send to the client or else you will get a 500 Error when the user tries to link it up.
Following the steps on a basic level, to have a Lightspeed user give my application access to their Lightspeed 'Company' I need them to access a URL and then login to Lightspeed (if they haven't already) then choose the company to give me access to.
(Lightspeed is broken up into Companies, and then sub-sections called 'Sites' -- so think of McDonalds as a Company, they would have 'Sites' at Parramatta and Manly. Whichever user grants you that Authorization, you'll inherit their permissions so make sure they have access to all the sites in that company - assuming you're intending to see all their sites)
The URL you would send the client would be this:
based on the above example mine would be:
Requesting Authentication from the User
Your user will click this link, they may see a Lightspeed login screen, after which they will be presented with the below dialog box. They need to select their company then click Grant Access.
Note: The user that logs in, will grant their access levels to your integration. They must ensure they have all the needed permissions themselves (and access to the sites) that your integration will need.
(The "state" can be anything, or even ignored - it can be used to add extra information to tag what to do with the response. Most often people attach the SiteID here)
The steps to take on your end will vary depending on what library/system you are using to handle the OAuth 2.0 process, so compare these steps with documentation on your library/tool and you should get going.
Retrieving your Access & Refresh Tokens
As soon as the customer grants authority to their company, you will receive a GET request. My redirect URI was set to a webhook.site endpoint so I received this
The code aabd0416d88dc7c51456cecf83dc83
You'll then get the following response (note: you need to take that code and run this request quite quickly; I would suggest an automated process on your service).
You are now authenticated for that company, the access token can be used for requests to the API in an Authorization: Bearer header. The token expires after an hour. Use the refresh token (which does not expire) against https://api.kounta.
The refresh token should be stored in a database against that specific site. Do not lose the refresh token, it cannot be retrieved for you.
To generate a new access token, you would make a POST call to https://api.kounta.
The remaining steps on the Authentication page in our documentation should be sufficient at https://apidoc.kounta.com/authentication/
You can also contact developer support at firstname.lastname@example.org should you have further questions.