Bring your own authentication

Command Protocol v2 authenticates messages, not users. Once your system holds a controller’s key it can control that controller directly, and it is free to decide who among its users may do so. This page describes the recommended way to build such a system.

The model

  Your users ──► Your platform ──► Controller (LAN, signed frames)
                      │
                      └── once per controller: SplashMe cloud (OAuth + envelope-key)

1. Establish trust once. The SplashMe account holder signs in through the OAuth2 flow, which proves they own the controller. Your platform fetches the controller’s envelope key and stores it against the controller.
2. Authenticate your own users your own way. Your platform decides who may send which actions. The controller sees only correctly signed frames.
3. Talk to the controller directly over the LAN from a hub, gateway or app on the same network.
4. Keep the cloud for what only it can do: audit event storage, access from outside the network, and re-fetching the key when it changes.

Responsibilities you take on

Responsibility	Guidance
Key storage	Store keys encrypted at rest and never expose them to end users or client devices you do not control
Counters	Use Unix seconds. If several of your components send to one controller, serialise them or accept the occasional dropped frame and retry after a second
Verification	Verify the tag on every frame you receive, including LAN responses, before acting on it
Read-modify-write	v1 pass-through “set” commands replace the whole object. Query first, then write
Ownership changes	If the SplashMe account holder removes your access or the controller changes hands, the cloud stops issuing the key. Re-check ownership periodically with the cloud API and drop the key when access is gone
Key changes	A controller’s key can change after a firmware update. Re-fetch the key when LAN verification starts failing

Reading without a key

A controller answers op: "state" on the LAN without a signature, and with the wire specification the state frame can be decoded without verifying it. This is enough for discovery, for showing the firmware version, and for read-only dashboards where the network is trusted. Anything that changes the controller requires the key.

What you cannot do

• Provision, pair, calibrate or reset a controller, whether over the LAN or through the cloud; those operations are reserved for the SplashMe app.
• Connect to the SplashMe MQTT broker. Cloud access is through the REST API only.
• Derive keys for controllers you have not been granted access to.