Nuki Bridge HTTP API V1.13.0
30.11.2021
1. Introduction
The REST API on the Nuki Bridge offers simple endpoints to list all available Nuki Smart Locks and Nuki Openers, retrieve their current lock state and perform lock operations.
1.1 Abbreviations used
| Abbr. | Abbr. | Description |
|---|---|---|
| cm | Continuous Mode | Continuous Mode |
| lng | Lock 'n' Go | Unlock and lock again automatically |
| rto | Ring to Open | Nuki Opener State in which ringing the bell activates the electric strike actuation |
2. Calling URL
This is the address used to call the available services of the internal webserver.
The IP address is shown in the bridge settings within the Nuki App or can be retrieved from the bridge discovery URL.
The server is listening for incoming requests either on default port 8080 or the configured one if it has been modified within the Nuki App.
2.1 Example
The following base url will be used in upcoming examples:
3. Bridge discovery & API activation
Calling the URL https://api.nuki.io/discover/bridges returns a JSON array with all bridges which have been connected to the Nuki Servers through the same IP address than the one calling the URL within the last 30 days. The array contains the local IP address, port, the ID of each bridge and the date of the last change of the entry in the JSON array.
3.1 Example
{ "bridges": [ { "bridgeId":2117604523,"ip":"192.168.1.50","port":8080,"dateUpdated":"2017-06-14 T06:53:44Z" } ], "errorCode":0 } Once a bridge has been discovered on the LAN the API can be activated and the API token retrieved by calling the /auth command. The user has to confirm this request by pressing the button on the bridge. For more details see the description of the /auth command. Alternatively you can activate the API and set the token by managing the Bridge in the Nuki App.
If discovery is disabled via /configAuth or through the Nuki App, the IP is 0.0.0.0 and the port 0. In this case the /auth command fails with HTTP error 403.
3.1.1 Alternative via Nuki App
As an alternative you can activate and manage the Bridge API via the Nuki App by opening Burger menu > Manage my devices > Bridge and follow the described steps:
3.2 Token
We offer two ways of verifying calls to endpoints with a token:
| Method | Usage |
|---|---|
| Plain token | You can use the plain token for testing and in private, secured WIFIs or VLANs. |
| Hashed token | Use if you do not want to send the plain token within your API-calls. Note: Only available for the hardware bridge for now. |
3.2.1 Parameters
| Name | Parameter | Values | Example |
|---|---|---|---|
| Plain token | token | uint8[20] | 123456 |
| Timestamp | ts | YYY-MM-DDTHH:MM:SSZ | 2019-03-05T01:06:53Z |
| Random number | rnr | uint16 | 4711 |
| Hash | hash | sha256("ts,mr,token") | f52eb5ce382e356c4239f8fb4d0a87402bb95b7b3124f0762b806ad7d0d01cb6 |
sha256("2019-03-05T01:06:53Z,4711,123456") = f52eb5ce382e356c4239f8fb4d0a87402bb95b7b3124f0762b806ad7d0d01cb6
3.2.2 Example calls
Plain token: http://192.168.1.50:8080/info?token=123456
A hashed token will only be valid with a sufficiently current timestamp and can not be reused, to prevent replay attacks. So making two calls with the exact same timestamp will only work with different random numbers. To debug problems with non synchronous times you can check the current time on the bridge via bridge discovery
4 States and Actions
4.1 Device Types
Nuki device connected to the bridge.
0 ... smartlock - Nuki Smart Lock 1.0/2.0 2 ... opener - Nuki Opener 3 ... smartdoor - Nuki Smart Door 4 ... smartlock3 - Nuki Smart Lock 3.0 (Pro)
4.2 Modes
| mode | smartlock | opener | Description |
|---|---|---|---|
| 2 | door mode | door mode | Operation mode after complete setup |
| 3 | - | continuous mode | Ring to Open permanently active |
Note: Only modes 2 and 3 can appear in JSON elements, as the HTTP API is not available in the other modes.
4.3 Lock States
Possible lock states (used in Endpoints below).
| ID | smartlock | opener |
|---|---|---|
| 0 | uncalibrated | untrained |
| 1 | locked | online |
| 2 | unlocking | - |
| 3 | unlocked | rto active |
| 4 | locking | - |
| 5 | unlatched | open |
| 6 | unlocked (lock ‘n’ go) | - |
| 7 | unlatching | opening |
| 253 | - | boot run |
| 254 | motor blocked | - |
| 255 | undefined | undefined |
4.4 Lock Actions
Possible lock actions (used in Endpoints below):
| ID | smartlock | opener |
|---|---|---|
| 1 | unlock | activate rto |
| 2 | lock | deactivate rto |
| 3 | unlatch | electric strike actuation |
| 4 | lock ‘n’ go | activate continuous mode |
| 5 | lock ‘n’ go with unlatch | deactivate continuous mode |
4.5 Simple Lock Actions
Possible outcome of a simple lock action (mapping handled in the firmware of the device):
| action | smartlock / knob | smartlock / handle | opener |
|---|---|---|---|
| /lock | lock | lock | deactivate rto and cm |
| /unlock | unlatch | unlock | open |
To use this features your Nuki devices need the following firmware version:
| Nuki device | Firmware version |
|---|---|
| Bridge | 1.14.0/2.5.0 (or higher) |
| Smart Lock 1.0 | 1.8.0 (or higher) |
| Smart Lock 2.0 | 2.4.3 (or higher) |
| Opener | 1.3.0 (or higher) |
4.6 Doorsensor States
Possible doorsensor states (used in Endpoints below).
| ID | name |
|---|---|
| 1 | deactivated |
| 2 | door closed |
| 3 | door opened |
| 4 | door state unknown |
| 5 | calibrating |
5. Endpoints
/auth
| URL | http://192.168.1.50:8080/auth | |
|---|---|---|
| Usage | Enables the api (if not yet enabled) and returns the api token. If no api token has yet been set, a new (random) one is generated. When issuing this API-call the bridge turns on its LED for 30 seconds. The button of the bridge has to be pressed within this timeframe. Otherwise the bridge returns a negative success and no token. | |
| Response | JSON list containing the success of the authorization | |
| token | The api token | |
| success | Flag indicating the success of the authorization | |
| Errors | HTTP 403 | Returned if the authentication is disabled |
| Example-Call | http://192.168.1.50:8080/auth | |
| Example-Response | {"token": “token123”,"success": true} | |
/configAuth
| URL | http://192.168.1.50:8080/configAuth | |
|---|---|---|
| Usage | Enables or disables the authorization via /auth and the publication of the local IP and port to the discovery URL (https://api.nuki.io/discover/bridges). | |
| URL-Parameters | enable | Flag (0 or 1) indicating whether or not the authorization should be enabled |
| token | The api token configured via the Nuki app when enabling the API | |
| Response | JSON list containing the success of the operation | |
| success | Flag indicating the success of the authorization | |
| Errors | HTTP 400 | Returned if the given value for enable is invalid (neither 0 nor 1) |
| HTTP 401 | Returned if the given token is invalid or a hashed token parameter is missing. | |
| Example-Calls | http://192.168.1.50:8080/configAuth?enable=0&token=123456 http://192.168.1.50:8080/configAuth?enable=0&ts=2019-03-05T01:06:53Z&rnr=4711&hash=f52eb5ce382e356c4239f8fb4d0a87402bb95b7b3124f0762b806ad7d0d01cb6 | |
| Example-Response | {"success": true} | |
/list
| URL | http://192.168.1.50:8080/list | ||
|---|---|---|---|
| Usage | Returns a list of all paired Nuki devices | ||
| URL-Parameters | Token | The api token configured via the Nuki app when enabling the API | |
| Response | JSON array. One item of the following per Nuki device | ||
| nukiid | ID of the Nuki device | ||
| deviceType | Nuki device type
|
||
| name | Name of the Nuki device | ||
| lastKnownState | JSON list containing the last known lock state of the Nuki device | ||
| mode | ID of the lock mode (see Modes) | ||
| state | ID of the lock state (see Lock States) | ||
| stateName | Name of the lock state (see Lock States) | ||
| batteryCritical | Flag indicating if the batteries of the Nuki device are at critical level | ||
| batteryCharging | Flag indicating if the batteries of the Nuki device are charging at the moment | ||
| batteryChargeState | Value representing the current charge status in % | ||
| keypadBatteryCritical | Flag indicating if the batteries of the paired Nuki Keypad are at critical level | ||
| doorsensorState | ID of the door sensor state | ||
| doorsensorStateName | Name of the door sensor state | ||
| ringactionTimestamp | Timestamp of the last ring-action | ||
| ringactionState | Flag indicating if a ring-action is currently occuring or not (reset after 30 seconds) | ||
| timestamp | Timestamp of the retrieval of this lock state | ||
| Errors | HTTP 401 | Returned if the given token is invalid or a hashed token parameter is missing. | |
| Example-Calls | http://192.168.1.50:8080/list?token=123456 http://192.168.1.50:8080/list?ts=2019-03-05T01:06:53Z&rnr=4711&hash=f52eb5ce382e356c4239f8fb4d0a87402bb95b7b3124f0762b806ad7d0d01cb6 | ||
| Example-Response | [{ "nukiId": 1, "deviceType": 0, "name": "Home", "lastKnownState": { "mode": 2, "state": 1, "stateName": "unlocked", "batteryCritical": false, "batteryCharging": false, "batteryChargeState": 85, "doorsensorState": 2, "doorsensorStateName": "door closed", "timestamp": "2018-10-03T06:49:00+00:00" } },{ "nukiId": 2, "deviceType": 2, "name": "Community door", "lastKnownState": { "mode": 3, "state": 3, "stateName": "rto active", "batteryCritical": false, "timestamp": "2018-10-03T06:49:00+00:00" } }] |
||