Nuki Bridge (Local API)

Controls Nuki Smart Locks (v1, v2, v3, Ultra), Nuki Smart Door, and the Nuki Opener via the on-LAN Nuki Bridge HTTP API. Bearer-token auth, plain HTTP on port 8080, no cloud round-trip required.

Prerequisites

• A Nuki Bridge paired with at least one Nuki device via the Nuki iOS or Android app. Both the v1 hardware Bridge and the v2/v3 Bridge (built into the Smart Lock 3.0 Pro and Smart Lock 4.0 Pro) expose the same HTTP API.
• HTTP API enabled on the Bridge (Manage Bridge → Manage → Bridge configuration → HTTP API → Enable). Enabling the API requires a physical button press on the Bridge and returns a token.
• The Bridge and the GEM host must sit on the same LAN subnet. The Bridge does not answer requests routed from a different subnet by default, and there is no configuration to change that.
• Firmware: the API has been stable since Bridge firmware 1.9 (2018). Any current shipping firmware works.

note

The Bridge speaks plain HTTP on port 8080, not HTTPS. Do not front it with a reverse proxy that requires mutual TLS; the Bridge will not present a client certificate.

Setup steps

1. Open the Nuki app on your phone and go to Manage Bridge → Manage → Bridge configuration → HTTP API.
2. Toggle Enable API and press the physical button on the Bridge when the app prompts you. The app displays the newly-minted token — copy it to a secure store.
3. In GEM, open Devices → Add Device and pick the nuki_bridge driver.
4. Fill in the device row:
   • IP Address / Host — LAN IP of the Bridge (e.g. 192.168.1.50).
   • Bridge HTTP Port — 8080 (default, don't change unless you know why).
   • API Token — the token from step 2.
5. Save the device and let it connect. Then run the get_devices command on the device to enumerate paired locks.
6. For each Nuki device you want to control, create a zone:
   • Subsystem — lock for a Smart Lock or Smart Door, door or gate for the Opener.
   • Address — the numeric nukiId returned by get_devices (e.g. 12345678).

Attribute reference

Device attributes

Attribute	Required	Description
ip	✅	LAN IP of the Nuki Bridge.
token	✅	API token returned by the Bridge when HTTP API is enabled. Secret.
port		HTTP port, default 8080.
status_interval		Poll interval in milliseconds, default 15000. Minimum enforced at 5000.
request_timeout		Per-request HTTP timeout in milliseconds, default 10000.

Zone attributes

The driver populates these on each poll — the integrator does not need to enter them by hand.

Attribute	Type	Written by driver	Description
state	string	poll + post-command	locked, unlocked, unlatched, motor_blocked, undefined on locks. online, rto_active, open, continuous on the Opener.
battery_level	int	poll	Battery percentage on models with batteryChargeState; synthesised 10 or 90 on models that only report batteryCritical.
door_state	string	poll	open / closed when a Nuki door sensor is paired. Absent when no sensor.
remote_name	string	first connect	Human-readable name from the Nuki app (e.g. "Front Door"). Populated once.

Zone address format

<nukiId> — the plain numeric id returned in the nukiId field of /list. Example: 12345678.

Every Nuki device paired with the Bridge gets its own zone. Do not put a Nuki Bridge on multiple zones or try to share a zone across Nuki devices — the driver keys strictly on nukiId.

Commands

Verb-style commands take the zone address as address. Discovery commands are device-scoped.

Command	Applies to	Description
lock	Smart Lock / Smart Door	Fully lock the lock.
unlock	Smart Lock / Smart Door	Rotate to unlocked; latch stays extended.
unlatch	Smart Lock / Smart Door	Retract latch — door can be pushed open. Requires a working latch.
lock_n_go	Smart Lock / Smart Door	Unlock briefly then re-lock after the delay set in the Nuki app.
activate_rto	Opener	Arm Ring To Open — next doorbell ring releases the strike.
deactivate_rto	Opener	Disarm Ring To Open.
electric_strike_actuation	Opener	Immediately actuate the strike (open now).
get_devices	device	List all paired Nuki devices with nukiId, name, deviceType.
get_status	zone	Read live state for one Nuki device.
get_info	device	Bridge diagnostics — firmware, uptime, WiFi.

What we don't yet support

• Hashed-token auth (Bridge hashedToken mode with ts + rnr + hash). The current driver sends the plain token in the query string; that is acceptable on a trusted LAN. Hashed-token support is a future addition.
• Callback push updates (/callback/add). The Bridge can POST state changes to a GEM URL instead of GEM polling, which would drop poll latency to sub-second. The driver falls back to polling; wiring up an inbound callback endpoint is on the roadmap.
• Web/cloud API (api.nuki.io). The driver only speaks to a LAN Bridge; cloud-only accounts (where the user never installed a Bridge) are not yet supported. Nuki now sells locks with an integrated Bridge (Smart Lock 3.0/4.0 Pro) — those still expose the same LAN API.
• User / auth-code management. The Bridge API can list and add/remove user codes and RFID cards; this driver does not surface those yet.

Troubleshooting

• 401 unauthorized on every call — the token is wrong or HTTP API has been disabled on the Bridge. Re-enable it in the Nuki app and copy the new token.
• get_devices returns an empty list — no Nuki devices are currently paired with this Bridge, or the Bridge has lost pairing. Re-pair from the Nuki app.
• lockAction returns success but state never changes — the Bridge accepted the request but could not reach the lock over Bluetooth. Nuki recommends the Bridge sit within ~5 metres of the lock.
• Connection refused — HTTP API is not enabled on the Bridge, or a local firewall on the GEM host is blocking outbound to port 8080. Verify with curl http://<bridge-ip>:8080/info?token=<token> from the GEM host.
• State bouncing between locked and unlatched — the lock is mid-actuation. Increase status_interval above 10s so polls don't catch transitional states.