Moen Flo Smart Water Shutoff

Remote valve control, system-mode switching (home / away / sleep), and periodic telemetry (flow, water temperature, PSI, battery, alerts) for Flo by Moen / Moen Flo Smart Water Monitor + Shutoff devices via the api-gw.meetflo.com cloud REST API.

Auth is email + password; the driver mints a short-lived JWT session token, keeps it in memory, and re-mints it on 401 or when the token payload's exp claim passes. There is no persistent token stored on disk.

Cloud-only path

Moen Flo does not publish a local LAN API. This driver is a cloud driver — the GEM host must have outbound HTTPS to api-gw.meetflo.com. If the internet path is unavailable, valve commands cannot be sent even if GEM and the shutoff are on the same LAN.

Prerequisites

• A working Moen Flo (formerly Flo by Moen) cloud account with the shutoff already onboarded through the mobile app.
• The GEM host must be able to reach https://api-gw.meetflo.com on port 443.
• The account credentials used in GEM must belong to the account owner or a household member with control permission. Read-only shares can enumerate devices but the API returns 403 on valve actuation.
• MFA must be disabled on the account used with GEM. The password-grant /users/auth endpoint does not accept a second factor; if MFA is enabled the driver will loop on auth failed. If you want MFA on your main account, create a sub-account for GEM without MFA.

Setup

1. Navigate to Admin → Devices and click Add Device.
2. Choose moen_flo as the driver.
3. Fill in:
   • Moen Flo Account Email (username) — the address used to log in to the Flo mobile app.
   • Moen Flo Account Password (password) — stored encrypted.
4. Save the device. GEM will authenticate and discover all locations and shutoffs on the account.
5. Run the get_devices command on the device (from the device detail page, Commands tab) to list the shutoffs. The response includes each device's id, nickname, macAddress, and location_id.
6. Under Admin → Zones, create one zone per shutoff:
   • Subsystem: pick or create a plumbing/water subsystem (a security subsystem also works if you are treating the shutoff as an incident-response tool).
   • Address: paste the Flo device id (a UUID like a1b2c3d4-e5f6-7890-abcd-ef1234567890).
7. The zone's state attribute will populate on the next status poll (open / closed). Telemetry attributes (flow_rate, water_pressure, water_temperature, battery_level, alert_severity) follow.

Attribute reference

Device attributes

Attribute	Required	Description
username	yes	Moen Flo cloud account email.
password	yes	Cloud account password. Stored encrypted (gem-crypt: envelope).
api_base	no	Cloud endpoint. Defaults to https://api-gw.meetflo.com. Only change if Moen migrates the API host.
status_interval	no	Poll interval in ms. Default 60000, floor 15000.
request_timeout	no	HTTP request timeout in ms. Default 15000.

Zone attributes (populated by the driver)

Attribute	Type	Description
state	string	open if the valve permits flow, closed if shut.
flow_rate	float	Instantaneous flow in gallons per minute. Zero during no-flow windows.
water_pressure	float	Static line PSI at the shutoff.
water_temperature	int	Water temperature at the shutoff in °F.
battery_level	int	Battery percentage when the device reports it (mains-powered shutoffs may omit this).
alert_severity	string	One of clear, info, warning, critical — mirrors the highest pending notification on the device.
location_id	string	The Flo location UUID this shutoff belongs to. Populated on connect; used by set_system_mode.

Zone address format

zone.address = the Moen Flo device id UUID, e.g. a1b2c3d4-e5f6-7890-abcd-ef1234567890.

Run get_devices on the driver device to enumerate; the response contains one entry per shutoff with id, nickname, macAddress, location_id, deviceModel, and firmwareVersion.

Commands

Command	Args	Notes
open	address	Opens the valve (allows flow). Fires a status refresh 2 s later.
close	address	Closes the valve (stops flow). Fires a status refresh 2 s later.
set_system_mode	address, mode, revert_minutes	Sets the whole-location mode to home, away, or sleep. revert_minutes (2–1440) only applies to sleep; defaults to 120. The driver resolves the location from the zone or (if there's exactly one) from the account.
get_status	address	Refreshes and returns the full Flo device payload for the zone.
get_devices	—	Lists every shutoff visible to the account.
get_locations	—	Lists every location owned by the account, including the current systemMode.

Known limitations

• Leak-detection alert clearing must be done in the Moen Flo mobile app; the driver only surfaces alert_severity, it cannot dismiss alerts.
• Historic water-usage graphs (daily / monthly consumption) are not exposed by this driver. Only the live telemetry the cloud publishes on the device payload is mirrored.
• Sleep mode requires a revert; the API will reject set_system_mode(sleep) without a revertMinutes. The driver injects a 120-minute default, which reverts to home.
• Valve actuation is blocked while in sleep mode — the Flo cloud returns 403. Change to home or away first.
• Multi-shutoff accounts are supported (one zone per shutoff), but the driver polls sequentially with a 750 ms gap between devices to stay well under the account rate limit. If you have more than ~10 shutoffs on one account, consider raising status_interval.

Troubleshooting

Symptom	Likely cause
Log shows moen flo auth failed on connect with http 401	Wrong email/password, or MFA is enabled on the account. Sign in via the Flo mobile app to confirm credentials. Disable MFA or create a sub-account.
get_devices returns an empty list	The account has no shutoffs, or the account is a read-only share. Confirm ownership in the Flo app.
open / close returns 403	Location is in sleep mode. Call set_system_mode with mode: home first.
Zone state never reflects a manual actuation at the physical shutoff	The Flo cloud reflects hardware changes on its own schedule (typically 30–60 s). Lowering status_interval below that window will not help — the cloud is the bottleneck.
state reports null for a fresh zone	The first poll hasn't run yet. Wait status_interval ms, or run get_status manually.

References

• Flo by Moen (product page): meetflo.com
• Community protocol reference: pyflowater / Home Assistant flo integration source (unofficial).