Local Authentication

By default, hubs will only support HTTPS and will respond to any unauthenticated request from the local network with an HTTP 401.

Hub Discovery

Jilia hubs advertise mDNS using the values below:

name: HUB-{uuid}
port: 1337
host: {uuid}
type: 'jilia-hub'
protocol: 'tcp'
txt: 'mac:{mac addr}'

Example code for hub discovery using node module Bonjour:

var bonjour = require('bonjour')();

bonjour.find({type: 'jilia:hub'}, function(obj){
  console.log(obj.name);
});

Hub Authentication Mode

The hub can be placed into authentication mode by holding the button until the green and amber LEDs begin pulsing a heartbeat pattern then releasing the button. This will place the hub in authentication mode, which will last for 30 seconds, or until a valid token is issued. The LEDs should return to normal once authentication mode ends.

Requesting Access Credentials

Access Credential Request

Once the hub has been placed into authentication mode, a user may request credentials by making a POST request with the JSON body as outlined below.

POST http://{ip}:{port}/access
{
  userId: {a unique user ID to be assigned to the token},
  expiresIn: {duration, in seconds, that the token is valid.  Use 0 for a token that doesn't,expire}
  accessLevel: {see Access Levels},
  activationKey: {the activation key for the hub}
}

cURL Example:

curl -XPOST -H"Content-Type: application/json" -d '{"userId":"timmy","expiresIn":0,"accessLevel":"developer","activationKey":"key here"}' http://:1337/access

Access Credential Response

Status Meaning
200 Request granted, response should contain a JSON WebToken object that can be used to make API requests
400
Error Meaning
invalid request The request did not contain a valid JSON body
duplicate userId The provided userId already has a valid token
invalid activationKey The provided activationKey was invalid
invalid state The hub it not allowing authentication requests
other A description of invalid or missing parameters provided to the request

Access Levels

The access levels available, and what devices are available for a given access level will be customer specific. Below are some guidelines for specifying access levels:

  • user - This level will generally provide access to all "normal" devices. Lights, thermostats, etc.
  • developer - This level will generally provide the same access as user plus any 'service' type devices that might be required

Making API Calls

Once a user has been granted credentials, API calls can be made by including the credentials in either the HTTP Authorization header, or as the access_token query parameter

API Responses

If the request fails authentication, it will return an HTTP 401 status and one of the following error messages:

  • token expired - the provided token has expired
  • invalid token - the token was not a valid JWT, was not signed by the hub, or was revoked

Managing Access Credentials

The LocalAuthenticationService service can be used to revoke credentials that have been issued by the hub. Revoked credentials will no long be valid, even if they have not expired

References

JSON Web Tokens

The tokens provided by the API are JSON Web Tokens. These tokens are signed by the hub using a private key which is also used to verify that the provided token was issued by the hub. This prevents the tokens from being tampered with after being issued.