API Authentication

Before you start using the Aretas IoT API, you need to implement and understand Authentication in your platform. In general, the Aretas API utilizes Token Based Authentication. 

Most Aretas API methods require an access token to authenticate the user. A token is acquired by logging into the Authentication endpoint and receiving a token as a response. The token is subsequently used in the Request Header of HTTP requests. There are 3 ways to acquire a token.

1. Form Submission

This method allows you to submit a form and get the token as a JSON object in response.

HTTP Method: POST

Path: https://{hostname}/rest/authentication/f

Consumes: application/x-www-form-urlencoded

Produces: A Response containing the access token

2. Query URL

This method produces the token, in the response body as a result of a GET request containing the username and password as query parameters.

HTTP Method: GET

Path: https://{hostname}/rest/authentication/g

Produces: A Response containing the access token

Example: https://iot.aretas.ca/rest/authentication/g?username={username}&password={password}

Example Result: g87023gjept1iak0t4emno2ltlanv

Python Example:

def gettoken():
    response = requests.get(API_URL + "authentication/g?username=" + USERNAME + "&password=" + PASSWORD);
    if response.status_code >= 200 :
        return response.content.decode()
    else:
        return None

3. JSON / POST

This method produces the token as a result of a POST containing a Credentials user object.

A Credentials object (in JSON) is an Object containing the username field and password field:

{
    username: "username",
    password: "password"
}

HTTP Method: POST

Path: https://{hostname}/rest/authentication/j

Produces: A Response containing the access token

Javascript Example:

$.ajax({
    dataType: "text",
    contentType: "application/json",
    type: "POST",
    url: ASNAPIURL + "authentication/j",
    data: JSON.stringify({
        username: "username",
        password: "password"
    }),
    success: function (data) {
        bearerToken = data;
        Cookies.set('X-Aretas-Bearer', bearerToken);
    },
    error: function (data) {
        console.log(data);
        alert("Could not log you in, please try again");
    }
});

Using the Access Token

Your application should store the API Token temporarily and use it in the Request Header (Specifically Authorization: Bearer {token}) of subsequent requests to the API. For example:

Javascript

(Query sensor status example)

//get the access token and store it in a local cookie
$.ajax({
    dataType: "text",
    contentType: "application/json",
    type: "POST",
    url: ASNAPIURL + "authentication/j",
    data: JSON.stringify({
        username: "username",
        password: "password"
    }),
    success: function (data) {
        bearerToken = data;
        //store the token in a local cookie
        Cookies.set('X-Aretas-Bearer', bearerToken);
    },
    error: function (data) {
        console.log(data);
        alert("Could not log you in, please try again");
    }
});

$.ajax({
    beforeSend: function (xhr) {
        //set the Authorization header with the token
        xhr.setRequestHeader('Authorization', "Bearer " + bearerToken);
    },
    dataType: "json",
    data: jsonStr,
    contentType: "application/json",
    type: "POST",
    url: ASNAPIURL + "sensorstatus/list",
    success: function (data) {
        onSensorsStatusOK(data)
    },
    error: function (data) {
        console.log("Error calling sensor statuses");
        console.log(data);
    }
});

Python

(Send data to API example)

def gettoken():
    # get the API token
    response = requests.get(API_URL + "authentication/g?username=" + USERNAME + "&password=" + PASSWORD);
    if response.status_code >= 200 :
        return response.content.decode()
    else:
        return None


# send data to the API
def sendToAPI(mac, timestamp, dataType, dataValue):
    response = requests.get(API_URL + "secured/std/get" + "?t=" + str(timestamp) + "&m=" + str(mac) + "&st=" + str(dataType) + "&d=" + str(dataValue), headers={"Authorization": "Bearer " + API_TOKEN})
    return response.status_code