Authentication

v3 of the API implements the same token-based authentication as the v2 API.

To access the API you will need an API key (token), issued by Wattwatchers.

Your API key is available via the Fleet Management app. Please contact Wattwatchers support if you don't have the details for accessing this app. Your API key is available under the profile menu (the person icon in the top-right of the Fleet Management app):

Bearer token authentication

Bearer token authentication requires your application to provide an Authorization header with your API key preceded by the text Bearer.

HTTPcURLPythonJavascript

GET /devices HTTP/1.1
Host: api-v3.wattwatchers.com.au
Content-Type: application/json
Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X GET -H "Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" "https://api-v3.wattwatchers.com.au/devices"

In python, using the popular requests library, you can do this by passing a dictionary via the headers argument:

import requests
# TIP: It's best that your API key be stored in an environment variable (retrieved using os.getenv()), not in your code e.g.:
# import os
# api_key = os.getenv('YOUR_ENV_VAR_NAME')
#
# This is a simplified example to demonstrate the concept:
api_key = 'key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' # insert your actual key here
headers = {
'Authorization': 'Bearer %s' % api_key
}
response = requests.get('https://api-v3.wattwatchers.com.au/devices', headers=headers)

In Javascript (client-side), using the axios library:

const axios = require('axios');
const api_key = 'your_secret_api_key'

// set the default headers for all requests
const api = axios.create({
baseURL: 'https://api-v3.wattwatchers.com.au',
headers: {
    'Authorization': `Bearer ${api_key}`
}
});

api.get('/devices')
.then(function (response) {
    // handle success
    console.log(response);
})
.catch(function (error) {
    // handle error
    console.log(error);
})
.then(function () {
    // always executed
});

How to get an API key

Please contact the Wattwatchers team to have an API key setup. We will distribute the API key to you securely once we have set it up and assigned the correct devices and related permissions.

Keep your API key secret!

When designing your application, be sure not to expose your API key insecurely. This includes not hard-coding it into your application and putting it in source control, or in a browser-based app storing it in cookies or local storage etc.

Best practice for server-side applications is to store your API key as an environment variable and accessing this programatically. For browser applications, this should only be returned to your app after you have authenticated the user and via https (SSL).

Do not send your API key via insecure email or web-based communications tools. If you do need to communicate your key with us (i.e. to disambiguate between multiple keys you have access to), please use the last 5 characters of the API key only. e.g. "...3je2f"

What happens if my API is disclosed?

If we become aware of your API key being disclosed via insecure means (e.g. to our support personnel or in an email we receive) we will automatically retire your existing key and refresh it. We will notify the technical contact(s) that we have on file if this occurs.

What is the API key (Bearer token)?

The API key is a string token that identifies and authenticates a client application to the API.

The API key represents a set of permissions to a pre-defined set of devices that the client application is permitted to access (read and modify).

This token lives until it is expired by Wattwatchers.

If you need to restrict access to a subset of devices, you will need to arrange creation (by Wattwatchers) of a new API key for your organisation.