Kounta by Lightspeed uses an OAuth 2.0 compliant RESTful API for easy integration with third-party applications.
Two types of authentication are available:
Developers can use this method for the convenience of session-free testing.
To use Basic Access Authorization, send an Authorization
header with each
request with the client_id:client_secret
string encoded in
Base64. E.g.:
Authorization: Basic eHh4Onl5eQ==
This will only allow you to access data from your own Kounta by Lightspeed company. To allow other companies to grant permissions to your add-on you'll need to implement OAuth2 flows.
Read this article for a detailed description of Basic Access Authorization.
Production applications must use OAuth 2.0 for authentication.
OAuth 2.0 is a little complicated. Fortunately for you, there are plenty of great libraries you can use to simplify the process. We highly recommend using them over trying to implement the protocol on your own.
If you prefer to use your own implementation rather than an OAuth 2.0 library, the spec has everything you'll need to know.
Once you have your client_id
and client_secret
, use these URLs
to authenticate:
https://my.kounta.com/authorize
https://api.kounta.com/v1/token
For authorisation with OAuth2 you should be sending the user's browser to the authorize endpoint with
client_id
, redirect_uri
, state
and response_type
parameters,
ensuring that your redirect_uri matches the ones you configured in Kounta by Lightspeed.
E.g.:
https://my.kounta.com/authorize?client_id=YOURCLIENTID&redirect_uri=http%3A%2F%2redirect.com&state=a1b2c3d4&response_type=code
This will take the user to a Kounta by Lightspeed page to login (if they haven't already) and then present them with a permissions dialog to grant access to your add-on.
On success, it redirects to your redirect_uri with code
and state
query parameters so you can generate access tokens and make subsequent requests for this company.
Using the code
parameter, you fetch an access token and refresh token for this company by doing a POST to
https://api.kounta.com/v1/token
with code
, client_id
, client_secret
, redirect_uri
, and grant_type=authorization_code
.
This will return something similar to:
The company is now authenticated. You should store the refresh_token
in a database against that company.
The access_token
should then be used for subsequent requests to the API in an Authorization: Bearer
header.
Each access token expires in 1 hour, and you should use the refresh token (which does not expire, unless revoked) to generate new access tokens as needed.
To refresh the access token, do a POST request to https://api.kounta.com/v1/token
with refresh_token
, client_id
, client_secret
, and grant_type=refresh_token
.
This will return something similar to:
To revoke any type of token, do a POST request to https://api.kounta.com/v1/revoke
with client_id
, client_secret
, and token
.
A successful response returns a HTTP status code 200
. This will return a response such as:
The API limits the number of requests based on the authentication type:
Every response for an authenticated request will include several headers that describe your current limit (including the request that was just made):
X-Ratelimit-Limit
- Your total limit.X-Ratelimit-Remaining
- The number of requests you
have remaining.X-Ratelimit-Reset
- The time when your limit will
be reset.If you have reached your limit, further requests will return a
429 Too Many Requests
. You will not be able to make any
more requests until the X-Ratelimit-Reset
time has been
reached.
All endpoints will count towards your limit. Please keep in mind that
following redirect requests (that is requests that return
302 Found
) will cause your client to make two requests
and take two off your limit. An example of this is
/companies/me
.
If you need a limit increase please contact developers@kounta.com