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 URI from https://webhook.site - these are free but be aware they are publicly accessible so only suitable for testing.

Building the Authentication URI

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 URI 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 URI 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 URI you would send the client would be this:
https://my.kounta.com/authorize?client_id=YOURCLIENTID&redirect_uri=YOURREDIRECTURI&state=a1b2c3d4&response_type=code

based on the above example mine would be:

https://my.kounta.com/authorize?client_id=m7BhMdi1NO6UYl38&redirect_uri=https://webhook.site/e579c750-b531-4f1e-8055-6b83ea5a7f42&state=a1b2c3d4&response_type=code

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  aabd0416d88dc7c51456cecf83dc83f98fccbb99 is what I will need to use on  https://api.kounta.com/v1/token.json get the access and refresh tokens.

{
"code": "aabd0416d88dc7c51456cecf83dc83f98fccbb99",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"grant_type": "authorization_code",
"redirect_uri": "https://webhook.site/e579c750-b531-4f1e-8055-6b83ea5a7f42"
}

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.com/v1/token.json to get fresh tokens.

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.com/v1/token.json that will look like this:

{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "REFRESH_TOKEN_YOU_GOT_EARLIER",
"grant_type": "refresh_token"
}

Still Stuck?

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 developers@kounta.com should you have further questions.