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:

  1. The user picks a Home and starts adding a device.
  2. The client scans the node's QR code, which carries its local pairing details.
  3. The client pairs with the node locally and asks it to scan for Wi-Fi networks.
  4. The user chooses a network and enters the password.
  5. The client asks the cloud to initiate association, and gets back a request ID and a challenge.
  6. The client passes the challenge to the node over the local link; the node signs it with its private key.
  7. The client returns the node's answer to the cloud, which verifies it 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.