ha-wyzeapi: a Home Assistant bridge to Wyze devices built on an unofficial API

The component mimics the app, and that is the whole risk

The README states the central fact in its second sentence. This is a custom component to allow control of various Wyze devices in Home Assistant using the unofficial API, and it notes that this mimics the Wyze app and therefore access may be cut off at any time.

That is repeated in the potential downsides list as an unofficial implementation of the api and therefore may be disabled or broken at anytime by WyzeLabs.

The design reason for the mimicry is not documented here, but the shape of the project makes it obvious. The component depends on wyzeapy, a separate library at version 0.6.1 or newer, and the contributing section links a guide on intercepting data from the Wyze app, with a note for instructions on intercepting data from the Wyze app pointing at a post about intercepting pinned TLS connections on Android. That is a project built by reading what the phone app sends, which is a fundamentally different foundation from an API with documentation and a compatibility promise.

The practical consequence is that the failure mode is not a bug in your automation, it is a login that stops working on a Tuesday because the vendor changed something in the app, and nothing in the repository can prevent that. The README is honest about it, which is more than most projects in this position manage, but honesty is not the same as mitigation.

For a user with a Wyze bulb in a lamp that also has a physical switch, that risk may be acceptable. For a user whose alarm system depends on a Wyze lock entity, it is a different conversation.

What is actually controllable, and what has been switched off

The highlights list is short enough to take at face value, and one entry in it is not what it was.

Control Wyze Bulbs as lights through HA. Control Wyze Plugs as switches through HA. Turn on and off Wyze Cameras. Locking, locking back and viewing the status of lock and door for the Wyze Lock.

And then there is the entry with a caveat attached: Use Wyze Cameras as motion sensors, with the note Disabled following API usage incident with Wyze.

That is the most informative line in the whole document, because it shows the failure mode in practice. The motion sensor path was not removed for a technical reason, it was removed because the way it was implemented was noticed. A component that polls a camera for movement on a schedule, on a server, at scale, looks from the vendor's side like something that is not a user running their own device, and the response was to withdraw access.

The remaining camera capability is the simple on and off, which is a much narrower request surface. The lock support, which covers locking, locking back and status, is the most consequential feature here and the one where an access withdrawal would hurt most.

The second item in the potential downsides is worth reading for what it reveals about the authentication story. The line about requiring two factor authentication to be disabled on your account is struck through in the readme, and the replacement states that Two Factor Authentication is supported as of version 2021.9.2. So the component now handles two factor authentication, and the older requirement that you disable it on your account no longer applies.

Installing through HACS, and what the setup asks of you

The install path is HACS, and the readme marks it as highly recommended. The steps are spelled out in full, and they are worth following in order because the first one is a prerequisite rather than an action.

Have HACS installed, this will allow you to easily update. Add the repository as a custom repository as Type: Integration. Click install under Wyze Bulb and Switch Api Integration in the Integration tab. Restart HA. Go to Integrations in the config interface. Click ADD INTEGRATION. Search for Wyze Home Assistant Integration, with the note that if it does not appear, hard refresh the browser with ctrl+F5 and search again. Then enter your email, password, keyid and apikey when prompted, and the readme links Wyze's own documentation on creating an API key for anyone who does not know how to generate the keyid and apikey. Finally click SUBMIT.

The credentials are worth pausing on. You are handing a third party component your account email, your account password, and your API key, all inside Home Assistant, which is the machine that holds the credentials for every other service in your home. The code is open, the licence is permissive, and the project is a single maintainer with an issue tracker and an IRC channel, and the permission of the component to reach the Wyze cloud is exactly what the account credentials grant.

The last step of the flow is also the one most likely to be misread. Click SUBMIT and profit, as the readme puts it. The component then creates its entities, and the usage section describes what they look like. Entities show up as light.<friendly name>, switch.<friendly name>, binary_sensor.<friendly name> or lock.<friendly name>, for example light.livingroom_lamp, and the readme links the standard Home Assistant documentation pages for interacting with lights, switches and camera motion sensors.

Those entity names are the visible contract with the rest of Home Assistant. Once a Wyze bulb is a light entity, it works with every automation, script and dashboard that already knows what a light is, and that is the value the integration adds over talking to the API yourself.

Python 3.13 only, and a dependency on Home Assistant 2026.1

The project metadata is strict about versions, and the constraint on Python is the one that will surprise people.

The project requires Python >=3.13.2,<3.14. That excludes 3.14, which is unusual to see as an upper bound on a library rather than a lower bound, and it means the component is tied to a narrow interpreter window. The ruff configuration agrees, setting target-version to py313 and line-length to 88, with double quotes and space indentation.

The Home Assistant dependency is homeassistant>=2026.1.0, which means the component needs a recent Home Assistant release to install at all. That is a sensible choice for a custom component, since the Home Assistant custom component API changes between versions, but it does mean you cannot run this on an older Home Assistant.

The build system is hatchling, with the wheel packaging the custom_components directory. The runtime dependencies are minimal and correct for the job: homeassistant itself, wyzeapy for the API work, and websockets.

The development group is more interesting, because it shows how the project is tested. aiousbwatcher at 1.1.2 and pyserial at 3.5 are there so tests can emulate Wyze devices rather than talk to real hardware, and pytest with pytest-asyncio, plus ruff for linting, covers the rest. The repository root also carries a .pre-commit-config.yaml, a .gitleaks.toml, a .reuse/ directory, a LICENSES/ directory, and .issuetracker with .issuetracker.license and hacs.json with hacs.json.license, which is the REUSE licensing machinery and means every file in the tree, including the issue templates and the HACS metadata, carries a declared licence. The gitleaks configuration shows the project scans for committed secrets, which is a sensible precaution for a repository that deals with API keys.

Debugging, which starts by turning on the logger

When something does not work, the project asks you to change the logger configuration before you file anything, and this is a small piece of YAML that you add to your configuration.yaml.

logger:
 default: warning
 logs:
   custom_components.wyzeapi: debug
   wyzeapy: debug

There are two entries because there are two layers to debug. The custom_components.wyzeapi logger covers the Home Assistant integration itself, and the wyzeapy logger covers the library underneath it that actually speaks to the Wyze cloud. When the integration is not finding a device, or a device is found but will not respond, the two logs tell you which layer is at fault.

The process is four steps. Add the snippet to configuration.yaml, restart Home Assistant, verify you are still having the issue, and then file it in the repository with every provided field filled in. The project asks for the full form because a bug report for a custom component without the debug output is usually not reproducible.

Support is organised around the same channels as development. There is an IRC channel, #wyzeapi on Libre.Chat, the discussions tab on the repository, the wiki, and an issue tracker for bugs and feature requests.

An alternative worth considering, and what the project would rather you did

The honest alternative is not another Home Assistant integration, it is not using the unofficial path at all.

Wyze publishes an official API, and the readme points you at it. The note for anyone who does not know how to generate the keyid and apikey links Wyze's own documentation, Creating an API Key, and the credentials the component asks for are exactly the credentials that official API uses. So there is a path where you point your automation at the vendor's supported interface instead of at an emulation of the vendor's mobile app, and the readme's own funding section points the same way, asking people to support Home Assistant first, through swag or a Nabu Casa subscription, on the grounds that none of this could happen without them.

The difference in approach is real. The official API gives you a contract, however narrow, and a failure that says the API changed rather than a failure that says the app changed. The unofficial path gives you the whole device surface, including locking and locking back, which an official consumer API may not expose at all, and it gives it to you with no guarantee about tomorrow.

There is a second alternative that the project itself points to, and it is the one the maintainer would most like you to take. Support Home Assistant. The component is a custom component in Home Assistant, and every part of it depends on Home Assistant continuing to exist and continuing to accept custom components, and the ask in the funding section is that support goes to Home Assistant rather than to the author.

So the comparison is not with a rival integration. It is between three options: use Wyze's official API and accept a narrower device surface, use this component and accept that access can be withdrawn, or use devices with an official Home Assistant integration and skip the question.

Editorial conclusion

ha-wyzeapi fits a Home Assistant user who owns Wyze bulbs or plugs and wants them in automations without waiting for a supported integration, and it fits anyone willing to accept that the underlying API can be withdrawn at any time. It does not fit a deployment where device control has to keep working, since the project itself lists that as a potential downside, and it does not fit a user who wants camera motion sensing, which the project has disabled. Check three things before you commit. Check that your device type is actually covered, because the camera motion sensor path is currently off, the camera on and off path remains, and the lock support covers locking, locking back and status. Check that you are comfortable with the credentials, because the component asks for your email, password, keyid and apikey, and the keyid and apikey come from Wyze's own API key documentation. And check the version floor, because the project requires Python 3.13.2 or newer with 3.14 excluded, and Home Assistant 2026.1.0 or newer. The last push was on 2026-09-18, the newest release listed is v0.1.39 from 2026-08-06, and the license is Apache-2.0.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. SecKatie/ha-wyzeapi on GitHub