Skip to main content

User–Node Association

Association is how a node stops being anonymous hardware and becomes this user's device. It happens once per node, during setup, and it is what gives a user the right to see and control it afterwards.

Groups are the ownership boundary​

A node is never associated with a bare user account. It is associated into a Group — what the phone app presents as a Home — and permission flows from membership of that Group. One consequence worth internalising early: sharing a Home shares its nodes, and moving a node between Groups moves who can reach it.

Every other feature that asks "is this user allowed to do that" resolves through the same boundary, including group control and automations.

What happens during setup​

From the user's side this is a few taps in the phone app. Underneath, the client, the node and the cloud complete a three-way handshake:

Seven steps between three actors: the client picks a Home, scans the node's QR code and pairs with it locally, gets a Wi-Fi list back and takes the user's network and password; the client then asks the cloud to initiate association and receives a request ID and challenge; it passes the challenge to the node over the local link, where the node signs it without the key ever leaving; the client returns the signed answer to the cloud, which verifies it against the registered certificate and completes the association

Why this is secure​

The node proves possession of the private key matching the certificate the deployment already registered. A client cannot claim a node it has not physically reached, because the challenge travels over the local link, and it cannot forge the answer, because the key never leaves the device.

Two failure modes follow directly, and both look identical from the app:

  • The certificate on the device does not match the registered one — usually a node flashed with another node's factory image.
  • The node was never registered at all. Generating credentials does not register them; see Device credentials.

Removing a node​

Disassociation reverses the grant and cleans up the state that hung off it. A node that has been removed must be provisioned again before another user can add it, which is deliberate — it is what stops a resold device from staying visible to its previous owner.