Authentication

Basic Access Authorization

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.

OAuth 2.0

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:

• To request authorization: https://my.kounta.com/authorize
• To get access tokens: https://api.kounta.com/v1/token

Authorization

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.

Tokens

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.

Refreshing Tokens

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:

Revoking Tokens

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:

Rate Limiting

The API limits the number of requests based on the authentication type:

• Basic Access Authorization: 60 requests per minute.
• OAuth 2.0: 180 requests per minute.

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