2023.2: ESPHome deprecated API password: how to update to encryption key

If you run ESPHome separately from HA (separate Docker container, for example) and have existing ESPHome devices that are now warning about deprecated passwords following an HA update to 2023.2 or later, here’s how to fix:

Go here, and copy the randomly-generated base64 key (or generate your own).


In your ESPHome configuration for each device, find the lines:

  password: "YOUR_PASSWORD"

Replace it with this, substituting in the key from above:

    key: "YOUR_BASE64_KEY"

Install the new configuration to the device. Once it restarts, it will try and fail to communicate with HA (might take a while):

As soon as you see that message, go to the HA Integrations page (or refresh it if you’re already there), and you should see an alert prompting you to reconfigure the device:


Click the Reconfigure button, paste in your base64 key where prompted, hit Submit, and it should all magically start working again.

Repeat for all devices — up to you if you use the same or different keys.


Hey, thanks for the info, but isn’t the release notes suggesting that encryption key should be exchanged in the background?

When you set up a new device in ESPHome and next add it to Home Assistant, they will be able to exchange encryption keys. Removing the need for you to find, copy & paste those. Just a single click and the setup is done! :rocket:

For a newly-added device, yes. This guide is for updating existing devices without removing and re-adding.

Is there any prerequisite for this other than latest versions of HA and ESPHome? For me deleting and updating the esp with encryption did not help, it still asks for the key. (HAOS, official add-in…)

Latest is not a version.

Do you mean you followed the guide in my first post? If not — if you deleted the device and re-added — please start a new topic to discuss.

Yesterday in the stream it was said:

12:27: And right now what happens is the moment that you set up in home assistant it will automatically fetch the encryption key from your ESP home dashboard and there’s no copy pasting keys over. You don’t even have to remember it, it’s just done.
It also means that if you are today being like ‘Oh I should really add an encryption key that’s a good thing you’re saying there Paulus’. If you add an encryption key on your dashboard and you install it on your ESPHome device, HomeAssistant will automatically pick it up when it sees it cannot connect, so you don’t have to reconfigure anything in HomeAssistant, it will just automatically work.

This is telling me that there’s no need to copy/paste the encryption key even if the device is already configured.

Just asking these questions, because the documentation saying similar as well, and yes it is related to your post.

Does this change enable noise encryption? Won’t this be too overwhelming for older systems like the d1 mini?

Yes, it does enable noise encryption:


My devices are a load of D1 Minis, a Sinilink XY-USB, a couple of Shelly 1s, and some Gosund UP-111 plugs. All have come back online with no issues and are working well four hours on from the update.


Of course, HA 2023.2.0, ESPHome 2022.12.8. Thanks for showing me room for improvement!

That may be the case with the HA ESPHome add-on, which I don’t have so cannot comment — I’m running HA and ESPHome in separate Docker containers. I didn’t find any documentation on how to deal with this, hence my finding it out and posting the guide.

Well that makes sense, in case it should be a different discussion, but also should be mentioned somewhere in your solution as well…

1 Like

Thank you for this guide, for my case, after flashing my ESP they work without needing to enter the key. (Home Assistant OS)

On the other hand, I have one (esp32devkit) that refuses the OTA update even though I haven’t made any other modification, why before I didn’t have a flash problem with this ESP and now yes ?

The OTA partition on the ESP is too small. ESPHome needs to resize this partition, please flash over USB.

A question by the way, is it possible to do this:

    key: !secret key


The encryption needs a bit more space, it seems.

Try it and report back! :slight_smile:

I will test well but my ESP are difficult to access, this is what is causing me problems with the OTA update which does not pass :frowning:

Yes that’ll work…

And another tip…
Put this in your esphome secret:

<<: !include ../secrets.yaml

And you can use your HA’s secrets.yaml :wink:


I did update to the newest version (fresh install actually) but newly created esphome devices (from the add-on) still ask for the encryption key…

thank you for your reply :slight_smile:

I wonder, could encryption key be user defined, say 32 “a” letters, or, say “1234567890abcdefghijklmnopqrstuv” ? Or it must be base64 endoded? I like my passwords to be known by me not having to look somewhere each time. Personally i absolutely hate “randomly generated” passwords, because it’s easily lost and you’re stuck with non-working device…

That is the reason I moved it to secrets.yaml, so I have everything just in one place.

PS, it’s rather easy to obtains the key; it is a standart function now in esphome: