Internal API

Internal API for Network Management

The Internal API consists of a set of endpoints designed to govern the Ruuvi Network, such as whitelisting and blacklisting devices and/or IP addresses.

whitelist

POST https://network.ruuvi.com/whitelist

Whitelists a set of gateways.

Headers

Name	Type	Description
X-Internal-Secret	string	The secret to authenticate with the internal API

Request Body

Name	Type	Description
	object	JSON object containing a list of Gateway Mac Addresses and their corresponding Signing Secrets.

200 In case of success, a 200 OK is returned.

{
  "gateway": "<<MAC>>",
  "blockedAt": <<TIMESTAMP IF BLOCKED>>
}

400 If the provided data is invalid, 400 is returned.

403 In case no internal secret or invalid internal secret is provided, you will receive a 403 Forbidden.

POST /whitelist
{
    "macAddress": "ab:ba:cd:ba:cd:ba",
    "secret": "1234"
}

GET https://network.ruuvi.com/gwinfo

Fetches info for the gateway

Query Parameters

Name	Type	Description
gateway	string	Gateway Mac Address

Headers

Name	Type	Description
X-Internal-Secret	string	The secret to authenticate with the internal API

200

{
    "result": "success",
    "data": {
        "gateway": {
            "GatewayId": "<<GATEWAY MAC>>",
            "Whitelisted": <<UNIX TIMESTAMP WHEN WHITELISTED>>,
            "Connected": <<FIRST CONNECTED AFTER WHITELISTING>>,
            "Latest": <<MOST RECENT UPDATE>>,
            "InvalidSignatureTimestamp": <<MOST RECENT SIGNING REJECTION>>
        }
    }
}

401 If not authorized

Register a sensor to Cloud

POST https://network.ruuvi.com/register-sensor

This operation register a sensor with MAC address + secret to Cloud. The secret can be used to verify ownership of a sensor in case of a contested sensor.

Parameters are packed inside a JSON object, e.g. { "macAddress":"value", "secret":"value"}

Headers

Name	Type	Description
X-Internal-Secret	String	The secret to authenticate with the internal API

Request Body

Name	Type	Description
macAddress*	String	MAC address of sensor, 6 bytes. e.g. "AA:BB:CC:DD:EE:FF
secret*	String	Secret of sensor, e.g. "DE:AD:BE:EF:00:11:22:33

200: OK Sensor was added

{
    // Response
}

400: Bad Request A parameter is missing or data is invalid

{
    // Response
}

403: Forbidden Missing or invalid internal secret

{
    // Response
}

Register a subscription to be claimed by user

POST https://network.ruuvi.com/subscription-register

This endpoint is called by Ruuvi Shop after payment for user subscription is verified. Parameters are in JSON object of body.

Headers

Name	Type	Description
X-Shop-Secret*	String	Ruuvi Shop authentication secret

Request Body

Name	Type	Description
validDays*	String	Validity of subscription, e.g. 365
maxClaims*	Number	Number of sensors user can Claim
maxShares	Number	Number of shares user can have. Defaults to maxClaims * maxSharesPerSensor
maxSharesPerSensor	Number	Number of times one sensor can be shared. Defaults to 10
maxHistoryDays*	Number	Number of days of history user is allowed to retrieve. This does not affect sensors shared to this user.
maxResolutionMinutes*	Number	Best resolution user is allowed to retrieve. This does not affect sensors shared to this user.
subscriptionName	String	Name of subscription. Defaults to "Ultimate" (custom)
claimCode*	String	Code used to claim this subscription
creatorId	String	String id for creator of code, e.g. webshop account which triggered code generation

200: OK Subscription was registered

{
    // Response
}

403: Forbidden Missing or invalid authentication header

{
    // Response
}

400: Bad Request Missing required fields in payload

{
    // Response
}

500: Internal Server Error Server error, request might have been valid

{
    // Response
}

409: Conflict Subscription code already used

{
    // Response
}

Freebase Cloud Messaging to iOS devices - Proposal 2023-02-08

POST FCM://iOS

FCM is used to deliver push notifications to user applications. To receive the notification, user must register their device token with a POST to https://network.ruuvi.com/push-register

{ "notification":{ "body": $alertData, "title":"Ruuvi $alertType alert: $name" }, "alert":{ "title-loc-key": RUUVI_$alertType, "title-loc-args": [$alertType, $triggertype], "loc-key" : "RUUVI_$alertType_$triggerType", "loc-args" : [ $name, $currentValue, $alertUnit, $thresholdValue, $alertUnit] }, "content_available":1, "mutable-content":1, "token":$token, "email":$email, "type":"alert", "data":{ "name": $name, "id":$sensor_id, "alertType": $alertType, "triggerType": $triggertype, "currentValue": $currentValue, "thresholdValue": $thresholdValue, "alertUnit": $alertUnit, "alertData": $alertData } }

Request Body

Name	Type	Description
alertData	String	User-defined alert title. May be empty string
alertType*	String	Physical quantity of alert, one of: {"Temperature", "Humidity", "Pressure", "Movement", "Voltage", "RSSI", "noData"}
triggerType*	String	Type of violation, one of {"Over", "Under", "Different from"}
name*	String	User-configured sensor name
alertUnit*	String	Unit of alert, e.g. "C", "F", "K"
currentValue*	String	Current value of alerting sensor, in alertUnit units
thresholdValue*	String	Threshold value of alerting sensor, in alertUnit units
token*	String	FCM Token of receiver
sensor_id*	String	MAC Address of alerting senser
email*	String	User email