authentication.md

Authentication

Overview

Before you can use the RESTful API you need to create an authentication token This will enable you the access of the RESTful API.

On successfully claiming, you will receive an authentication token that you can use in your API requests.

Example of a locked API

This example demonstrate, that the RESTful API is still locked.

Request header :

GET /api/loads HTTP/1.1
host: example.com

Response body:

{
  "message":"api is locked, log in to receive an authentication cookie OR unlock the device.",
  "status":"error"
}

Get the authentication code

This example show how to unlock the RESTful API for an user.

As soon you start the request the physical buttons of the Wiser-µGateway will start flashing for 30 seconds. For a valid request, one of the physical buttons has to be pressed within 30 seconds!

1. Create a new user

   Request header:

   POST /api/account/claim HTTP/1.1
   Content-Type: application/json
   host: example.com

   Request body:

   {
     "user": "apiuser"
   }

   Request body payload:

   Property	Type	Description
   user	string	user name

2. Press any of the physical buttons of the Wiser-µGateway (LEDs are blinking with color blue/purple)

3. Get the response

   Response header:

   Content-Type: application/json

   Response body:

   {
     "data": {
       "user": "apiuser",
       "secret": "60650cf4-5d26-4294-b1f2-6c06adc9d0d8"
     },
     "status": "success"
   }

   Response body payload:

   Property	Type	Description
   user	string	user name
   secret	string	authentication token

Using the authentication code

The authentication token (also called Bearer authentication) is used in the HTTP request-header.

The client must send this token in the HTTP Authorization header when making requests:

Authorization: Bearer <token>

The following example demonstrates how to get all loads (lights & blinds) of your installation using the authentication token.

Request header:

GET /api/loads HTTP/1.1
Authorization: Bearer 60650cf4-5d26-4294-b1f2-6c06adc9d0d8
host: example.com

Response header:

Content-Type: application/json

Response body:

{
  "data": [
    {
      "id": 1,
      "type": "onoff",
      "name": "0000133a_0",
      "device": "0000133a",
      "channel": 0,
      "unused": false
    },
    {
      "id": 2,
      "type": "dim",
      "name": "0000144b_0",
      "device": "0000144b",
      "channel": 0,
      "unused": false
    },
    {
      "id": 3,
      "type": "motor",
      "name": "0000155c_0",
      "device": "0000155c",
      "channel": 0,
      "unused": false
    }
  ],
  "status": "success"
}