How to Authenticate Using the Konekt REST API

/ Written By Reuben Balik

What can you do with the Konekt REST API?

The short answer to that question:

  • everything.

The long answer to that question:

  • manage all aspects of your account.
  • activate SIM cards.
  • send and receive data with your device.
  • buy phone numbers.
  • And more!

We have architected our entire system so that everything on our device portal is built around our API.

This is obviously way too much to discuss in a single blog post so we’ll break it down into a continuing series of posts.

To start this off, let’s talk about the first thing you need to know when working with any REST API: how to authenticate.

We have provided multiple methods to login to the API that should work for whatever application you are building.

Session-based authentication with the Konekt REST API

For browser-based applications, the Konekt API supports creating sessions that can be restored by sending a cookie or an HTTP GET or POST parameter. Most browsers will automatically take care of sending the cookie for you so once you authenticate you don’t have to worry about a thing.

Let’s see how it works:

Issue an HTTP POST request for ‘/1/auth/session’ with your email and password:

POST /api/1/auth/session HTTP/1.1
Host: dashboard.konekt.io
Cache-Control: no-cache
Content-Type: application/json

{
   "email" : "someemail@konekt.io",
   "password" : "mypassword"
}

If all goes well, the server will respond with something like this:

{
   "success": true,
   "data": {
   "sesskey": "dkmh7j0moe8qogjtmv15rksl30",
   "userid": 395,
   "email": "someemail@konekt.io",
   "name": "Reuben Balik",
   "role": "",
   "partnerid": 1
   }
}

Here’s an example of how you would make that request on a webpage using jQuery:

var email = "youremail";
var password = "yourpassword";

$.post("https://dashboard.konekt.io/api/1/auth/session",
    {
        email:email,
        password:password,
    },
    function(data) {
        alert(JSON.stringify(data);
    });

Along with the JSON response, the server will also send back a cookie. If you are using a web browser, then that’s all you need. You are now logged in and future requests to the API from your browser will be authenticated automatically.

If you are not using a web browser or cookies are disabled then you can still use session authentication by taking the sesskey parameter in the response above and sending it with each request.

For example, to get user information you could issue a GET request to a URL like this:

/api/1/users/me?sesskey=dkmh7j0moe8qogjtmv15rksl30

Note that sessions do expire if you don’t make any requests for 20 minutes so you will get logged out automatically if you are inactive for longer than that period of time.

HTTP Basic Authentication with the Konekt REST API

We also support HTTP basic authentication for the API. This is a feature of HTTP itself and allows for authentication information to be attached as a header to each API request.

This is useful for situations where you are developing your own client outside of a browser where it may not be as simple to save the session key between requests.

To use this method, combine your email and password into a string separated by a colon like this:

someemail@konekt.io:mypassword

Then encode this string using the base64 algorithm and insert it into the HTTP “Authorization” header like this on every request:

Authorization: Basic cmV1YmVuQGtvbmVrdC5pbzpteXBhc3N3b3Jk

Since you are sending this on every request, there’s no need to worry about any credentials expiring.

Many HTTP tools and libraries will handle the encoding and insertion of this header for you.

With curl you can simply do it like this:

curl --user email:password url

For more information on HTTP Basic Authentication see http://en.wikipedia.org/wiki/Basic_access_authentication

API Keys

API keys are a simple way to connect to our API without needing to store an actual username and password in your configuration files.

All users can view and regenerate their API key on our device portal by clicking on the user menu at the top right and selecting “API Key”.

You can also view or generate your API key via the API itself. Using one of the above methods for logging in, you can view or regenerate your API key by doing a GET or POST to /api/1/users/me/apikey

(Use GET to view and POST to generate.)

The responses to both will look like this:

{
    "success": true,
    "data": {
        "apikey": "901YyOEtHOWNMnrcbdm04qoCCxUhVU"
    }
}

Once you know your API key, you can use it to execute any API endpoint, by simply including it as either a URL parameter or a parameter in the POST. For example, to see your user information with the key above you could do a GET request to

/api/1/users/me/?apikey=901YyOEtHOWNMnrcbdm04qoCCxUhVU

Note that for security reasons some sensitive endpoints are not accessible via API key.

Happy coding!


We’re always eager to read your comments, questions and suggestions on our community forum.