Gateway API

API for the Ruuvi Gateway

Gateway API uses a JSON based API to facilitate communication between Ruuvi Gateways and the databases by validating and forwarding the data.

Send sensor data

POST https://api.placeholder.com/dev/record

Sends a bulk of data to Ruuvi Network to be processed and stored.

Headers

Name	Type	Description
Ruuvi-HMAC-SHA256	string	Signature for the payload, signed with device specific keys.

Request Body

Name	Type	Description
data	object	Data object contains a formatted JSON blob of sensor data to be stored. Example below.

200

403 In case of an invalid signature, you will receive a 403: Forbidden.

Data payload consists of gateway information and an array of tag measurements as illustrated below.

{
	"data":	{
		"coordinates": "",
		"timestamp": <UNIX TIMESTAMP>,
		"gwmac":	"<GATEWAY MAC ADDRESS>",
		"tags":	{
			"<TAG ID 1>": {
				"rssi": <RSSI VALUE>,
				"timestamp": <MEASUREMENT TIMESTAMP>,
				"data":	"<HEX ENCODED DATA>"
			},
			"<TAG ID 2>": {
				"rssi": <RSSI VALUE>,
				"timestamp": <MEASUREMENT TIMESTAMP>,
				"data":	"<HEX ENCODED DATA>"
			},
			...
		}
	}
}

MAC address format: XX:XX:XX:XX:XX:XX (where XX is a hexadecimal digit in upper case). Example: "11:22:33:AA:BB:CC" MAC address is used in "<GATEWAY MAC ADDRESS>" and in "<TAG ID 1>", "<TAG ID 2>", ...

The signature is a HMAC (hash-based message authentication code) which is calculated using sha256 algorithm from a combination of headers and the message body. Ruuvi network validates the signature against the whitelisted gateways (see: Internal API).

Below is an example code for calculating the secret:

// Secret information is only existent on the device and Ruuvi Network
// but is not a part of the payload.
const secret = deviceId + deviceAddr;

// Signature body consists of the secret, random nonce, timestamp and message body
// These need to match the corresponding headers sent to Ruuvi network:
//   x-ruuvi-timestamp
//   x-ruuvi-nonce
const nonce = 'RANDOMLY GENERATED STRING';
const timestamp = Date.now();
const signatureBody = secret + nonce + timestamp + messageBody;

// Signature can then be calculated using the 'crypto' library. The finalized
// signature will be passed in the header:
//   x-ruuvi-signature
const crypto = require('crypto');
const signature = crypto.createHmac('sha256', secret)
    .update(signatureBody)
    .digest('hex');