secrets.yaml en ESPHome: protege Wi-Fi, API y OTA

Este artículo puede contener enlaces de afiliado. Si compras desde estos enlaces, el precio para ti es el mismo y la tienda me paga una pequeña comisión que ayuda a mantener Tecnoyfoto.

Albert BarnosellEditor y responsable de Tecnoyfoto

Cuando empiezas a utilizar ESPHome, es muy fácil acabar poniendo las contraseñas Wi-Fi, las claves de cifrado de la API y otras credenciales directamente dentro del archivo YAML de cada dispositivo.

Funciona, pero a medida que la instalación crece se vuelve más difícil de mantener y también resulta mucho más fácil exponer información sensible accidentalmente al compartir una configuración, hacer capturas de pantalla o guardar los archivos en Git.

ESPHome ofrece una solución muy sencilla: secrets.yaml.

Este archivo permite mantener las credenciales separadas de la configuración de los dispositivos y hacer referencia a ellas utilizando !secret.

En esta guía veremos cómo funciona, qué información conviene guardar dentro, qué cosas no protege y cómo recomiendo organizar los secretos cuando tenemos varios dispositivos ESPHome.

secrets.yaml mantiene las credenciales separadas de la configuración ESPHome que podemos querer compartir o reutilizar.

¿Qué es secrets.yaml?

secrets.yaml es un archivo YAML almacenado junto a nuestros archivos de configuración de ESPHome.

En lugar de escribir los valores sensibles directamente dentro de la configuración de cada dispositivo, les damos un nombre y los almacenamos en secrets.yaml.

wifi_ssid: "MiRed"
wifi_password: "mi-contraseña-wifi-larga"

living_room_encryption_key: "CLAVE_BASE64"

living_room_web_username: "admin"
living_room_web_password: "otra-contraseña-larga"

Después hacemos referencia a esos valores desde el YAML del dispositivo utilizando !secret:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

ESPHome resuelve esa referencia cuando procesa la configuración.

El nombre debe coincidir exactamente.

Por ejemplo:

!secret wifi_password

busca:

wifi_password:

dentro de secrets.yaml.

¿Por qué utilizar secrets.yaml?

La principal ventaja es separar funciones.

La configuración del dispositivo describe cómo funciona nuestro ESP32 o ESP8266.

El archivo de secretos contiene los valores que no queremos publicar accidentalmente.

Esto resulta especialmente útil cuando:

tenemos muchos dispositivos ESPHome;
reutilizamos las mismas credenciales Wi-Fi;
guardamos configuraciones en Git;
compartimos ejemplos YAML;
hacemos copias de seguridad;
utilizamos packages;
trabajamos con otras personas;
publicamos configuraciones ESPHome en Internet.

En lugar de copiar una contraseña Wi-Fi dentro de diez archivos YAML diferentes, podemos hacer que todos ellos utilicen el mismo secreto.

¿Qué deberíamos guardar en secrets.yaml?

Una regla sencilla puede ser esta:

si un valor concede acceso, autentica a una persona o dispositivo, o contiene información privada, probablemente debería estar en secrets.yaml.

Contraseñas Wi-Fi.
SSID de Wi-Fi si preferimos no mostrarlos al compartir configuraciones.
Claves de cifrado de la API nativa de ESPHome.
Credenciales OTA cuando todavía utilizamos contraseñas.
Claves de cifrado OTA en dispositivos que no utilizan la API nativa.
Contraseñas del punto de acceso de emergencia.
Usuarios y contraseñas MQTT.
Usuarios y contraseñas del servidor web.
Tokens.
Credenciales de servicios externos.
URL privadas que contengan información de autenticación.

Un ejemplo básico

Un archivo secrets.yaml sencillo podría contener:

wifi_ssid: "MiWiFi"
wifi_password: "contraseña-wifi-muy-larga"

living_room_encryption_key: "TU_CLAVE_BASE64_DE_32_BYTES"

living_room_ap_password: "contraseña-fallback"

living_room_web_username: "admin"
living_room_web_password: "contraseña-web"

Y la configuración ESPHome correspondiente podría utilizar:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  ap:
    ssid: "Living Room Fallback"
    password: !secret living_room_ap_password

api:
  encryption:
    key: !secret living_room_encryption_key

web_server:
  auth:
    type: digest
    username: !secret living_room_web_username
    password: !secret living_room_web_password

Utiliza una clave de cifrado API diferente para cada dispositivo

Recomiendo utilizar una clave de cifrado de la API nativa diferente para cada dispositivo ESPHome.

Por ejemplo:

living_room_encryption_key: "..."
kitchen_encryption_key: "..."
rain_sensor_encryption_key: "..."
garage_encryption_key: "..."

Es mejor que utilizar la misma clave de cifrado en toda nuestra instalación.

Si alguna vez se expone una de ellas, solamente tendremos que sustituir la clave correspondiente a ese dispositivo, en lugar de tener que considerar comprometidos todos nuestros nodos ESPHome.

El cifrado de la API y OTA no son lo mismo

Esta diferencia es importante.

La API nativa de ESPHome es el canal de comunicación utilizado normalmente entre el dispositivo ESPHome y Home Assistant.

Una configuración típica con la API cifrada sería:

api:
  encryption:
    key: !secret living_room_encryption_key

OTA, u Over-The-Air, es el mecanismo utilizado para instalar nuevo firmware a través de la red.

ESPHome 2026.9 y posteriores: OTA cifrado

A partir de ESPHome 2026.9, la configuración OTA nativa recomendada permite utilizar cifrado.

Si el dispositivo ya utiliza la API nativa cifrada, OTA puede reutilizar esa misma clave de cifrado del dispositivo:

api:
  encryption:
    key: !secret living_room_encryption_key

ota:
  - platform: esphome
    encryption:

Esta opción es preferible actualmente a utilizar una contraseña OTA independiente porque la propia transferencia del firmware queda cifrada.

Una contraseña autentica quién puede realizar la actualización, pero no proporciona por sí sola la misma confidencialidad para la imagen del firmware mientras viaja por la red.

Dispositivos existentes con firmware anterior

Aquí hay un detalle importante durante la migración.

Si un dispositivo existente todavía ejecuta ESPHome 2026.8 o anterior, no debemos sustituir directamente su contraseña OTA por cifrado obligatorio y esperar que la primera actualización funcione.

El dispositivo necesita primero disponer de un firmware capaz de ofrecer OTA cifrado.

Una migración práctica sería:

Mantener temporalmente el método OTA existente.
Actualizar el dispositivo a ESPHome 2026.9 o posterior.
Comprobar que el dispositivo ya está ejecutando el nuevo firmware.
Sustituir la configuración con contraseña OTA por OTA cifrado.

En un dispositivo completamente nuevo que vayamos a flashear mediante USB o puerto serie, podemos configurar OTA cifrado desde el principio.

OTA mediante contraseña en configuraciones anteriores

Todavía podemos encontrar configuraciones existentes como esta:

ota:
  - platform: esphome
    password: !secret living_room_ota_password

Continúa siendo útil durante una migración o cuando todavía no podemos utilizar OTA cifrado, pero para nuevas configuraciones con versiones actuales de ESPHome prefiero utilizar cifrado.

¿Y si el dispositivo utiliza MQTT en lugar de la API nativa?

Si un dispositivo no utiliza la API nativa de ESPHome, no tendremos una clave de cifrado API que OTA pueda reutilizar.

En ese caso, OTA puede utilizar su propia clave de cifrado:

mqtt:
  broker: !secret mqtt_broker
  username: !secret mqtt_username
  password: !secret mqtt_password

ota:
  - platform: esphome
    encryption:
      key: !secret living_room_ota_encryption_key

También en este caso recomiendo utilizar una clave diferente para cada dispositivo.

Protege el punto de acceso de emergencia

ESPHome puede crear un punto de acceso Wi-Fi de emergencia cuando no consigue conectarse a nuestra red habitual.

Si lo utilizamos, deberíamos protegerlo con una contraseña robusta:

wifi:
  ap:
    ssid: "Living Room Fallback"
    password: !secret living_room_ap_password

Mover la contraseña a secrets.yaml evita que aparezca en el YAML que compartimos, pero no convierte una contraseña débil en una contraseña segura.

Protege también el servidor web de ESPHome

Si activamos web_server, el dispositivo ESPHome ofrece una interfaz web local.

Yo no dejaría esa interfaz sin autenticación.

web_server:
  port: 80

  auth:
    type: digest
    username: !secret living_room_web_username
    password: !secret living_room_web_password

Las versiones actuales de ESPHome permiten autenticación Digest, que resulta preferible a Basic porque la contraseña no se envía directamente en cada petición.

El servidor web debería permanecer dentro de nuestra red local de confianza y no exponerse directamente a Internet.

La actualización OTA desde el servidor web es otro método diferente

ESPHome también puede permitir la carga de firmware a través de la interfaz web del propio dispositivo.

Este mecanismo es independiente del protocolo OTA nativo de ESPHome.

Si no necesitamos actualizar firmware desde la interfaz web normal, no hay razón para mantener habilitada esa vía adicional de actualización.

En dispositivos donde utilizo la interfaz web únicamente para monitorización local, prefiero mantener desactivado el OTA web salvo que realmente lo necesite.

Credenciales MQTT

Las credenciales MQTT también deberían almacenarse en secrets.yaml.

mqtt:
  broker: !secret mqtt_broker
  username: !secret mqtt_username
  password: !secret mqtt_password

Siempre que sea posible, conviene utilizar usuarios autenticados, credenciales diferenciadas y comunicación cifrada entre el dispositivo ESPHome y el broker MQTT.

¿Qué no deberíamos guardar en secrets.yaml?

No todo tiene que convertirse en un secreto.

Normalmente no hay ninguna razón para ocultar:

el modelo de placa ESP32;
los números GPIO;
los nombres de sensores;
los nombres de dispositivos;
los intervalos de actualización;
los filtros;
la configuración normal de los componentes;
los nombres públicos de las entidades.

Mover todos los valores a secrets.yaml no mejora la seguridad y hace que las configuraciones sean más difíciles de entender y mantener.

Utiliza los secretos para credenciales e información privada, no como un segundo archivo general de configuración.

secrets.yaml no es cifrado

Probablemente esta sea la limitación más importante que debemos entender.

secrets.yaml es un archivo de texto plano.

Su finalidad es mantener los valores sensibles separados de los archivos normales de configuración y reducir el riesgo de exposición accidental.

No protege esos valores frente a alguien que pueda leer directamente el archivo.

Tampoco elimina mágicamente las credenciales del firmware.

Por ejemplo, el ESP32 necesita conocer nuestras credenciales Wi-Fi para poder conectarse a la red, por lo que esos valores terminan formando parte del firmware que ejecuta el dispositivo.

Esto significa que secrets.yaml protege principalmente frente a la divulgación accidental dentro de los archivos de configuración. No sustituye la seguridad del dispositivo, las comunicaciones cifradas, las copias de seguridad protegidas o una buena segmentación de red.

Git y .gitignore

Si guardamos nuestra configuración ESPHome en Git, debemos asegurarnos de excluir secrets.yaml.

secrets.yaml
*.backup

Pero añadir el archivo a .gitignore solamente evita futuras incorporaciones.

Si anteriormente publicamos una contraseña Wi-Fi, una clave API o un token, eliminarlo de la versión actual del repositorio no es suficiente.

El valor antiguo puede seguir existiendo en el historial de Git.

En esa situación deberíamos considerar que la credencial ha quedado expuesta y cambiarla o revocarla.

Las copias de seguridad también contienen secretos

Es fácil centrarse en Git y olvidarse de las copias de seguridad.

Si nuestra configuración ESPHome está incluida dentro de una copia de seguridad de Home Assistant, secrets.yaml también puede estar incluido.

Esto es útil para recuperar la instalación, pero también significa que las copias de seguridad deben tratarse como información sensible.

Debemos protegerlas adecuadamente y comprobar además que podamos restaurarlas cuando realmente las necesitemos.

Utilizar los secretos de Home Assistant desde ESPHome

Home Assistant y ESPHome normalmente disponen de archivos secrets.yaml separados.

Si preferimos mantener determinadas credenciales comunes en un único sitio, ESPHome puede incluir el archivo de secretos de Home Assistant.

Dentro del archivo secrets.yaml de ESPHome podemos utilizar:

<<: !include ../secrets.yaml

Con la estructura habitual de directorios de Home Assistant, esto importa los secretos situados en el directorio de configuración superior de Home Assistant.

Utilizar un único archivo compartido o mantener archivos independientes es principalmente una decisión organizativa.

Personalmente prefiero que las claves específicas de ESPHome estén claramente identificadas para saber inmediatamente a qué dispositivo pertenece cada credencial.

Un sistema de nombres que pueda crecer

Cuando tenemos más de unos pocos dispositivos, utilizar buenos nombres empieza a ser importante.

En lugar de:

api_key_1:
api_key_2:
password_3:

es mejor utilizar nombres que describan tanto el dispositivo como la finalidad de la credencial:

rain_sensor_encryption_key:
rain_sensor_ap_password:
rain_sensor_web_password:

kitchen_encryption_key:
kitchen_ap_password:

garage_encryption_key:
garage_web_password:

Seis meses después seguiremos sabiendo exactamente para qué sirve cada valor.

Errores habituales

Secret not found

Si ESPHome indica que no puede encontrar un secreto, debemos comprobar:

el nombre exacto de la clave;
mayúsculas y minúsculas;
la ubicación de secrets.yaml;
la indentación YAML;
que realmente se esté incluyendo el archivo esperado.

Caracteres especiales en las contraseñas

Si una contraseña contiene espacios, dos puntos, almohadillas u otros caracteres que YAML pueda interpretar de una forma especial, conviene poner el valor completo entre comillas.

wifi_password: "Mi:Contraseña#Muy Larga!"

La configuración es válida pero el dispositivo no conecta

Que una referencia !secret sea válida solamente demuestra que ESPHome ha encontrado un valor.

No demuestra que ese valor sea correcto.

Si falla la conexión Wi-Fi, debemos comprobar el SSID real, la contraseña, cobertura, modo de autenticación y los registros del dispositivo.

Cambiar una clave API y perder la conexión con Home Assistant

Debemos tener cuidado al sustituir la clave de cifrado de la API nativa de un dispositivo que ya está funcionando.

Home Assistant necesita conocer la misma clave que el dispositivo ESPHome.

Si cambiamos un lado sin actualizar el otro, la conexión cifrada dejará de funcionar.

Mi checklist práctica

Utiliza !secret para contraseñas, claves y tokens.
Mantén secrets.yaml fuera de repositorios públicos.
Utiliza una clave de cifrado de la API nativa diferente para cada dispositivo.
En versiones actuales de ESPHome, utiliza preferentemente OTA nativo cifrado.
Protege el punto de acceso de emergencia con una contraseña robusta.
Autentica el servidor web y mantenlo dentro de la red local.
No expongas directamente el servidor web de ESPHome a Internet.
Trata las copias de seguridad como información sensible.
Cambia las credenciales si sospechas que han quedado expuestas.
Utiliza nombres claros que indiquen el dispositivo y la finalidad de cada secreto.

Conclusión

secrets.yaml es uno de esos buenos hábitos que merece la pena adoptar desde el principio cuando trabajamos con ESPHome.

No hace que un sensor sea más rápido, más preciso ni más fiable.

Lo que hace es mantener las credenciales fuera de la configuración normal de los dispositivos, reducir duplicaciones y permitir compartir o versionar nuestros archivos YAML de una forma mucho más segura.

Pero también es importante entender sus límites.

secrets.yaml sirve para organizar y reducir exposiciones accidentales; no es un sistema de cifrado.

La estrategia adecuada es combinarlo con claves diferentes para cada dispositivo, API cifrada, OTA cifrado cuando esté disponible, acceso web protegido, copias de seguridad seguras y una red que no exponga innecesariamente nuestros dispositivos ESPHome.

Una vez tenemos esta estructura bien organizada, añadir el décimo o el vigésimo dispositivo ESPHome resulta mucho más fácil de mantener sin acabar repartiendo credenciales por decenas de archivos YAML.

Continúa leyendo

Siguiente guía relacionada · 10 min de lectura

OTA en ESPHome: guía segura y solución de errores (2026)

Actualizado el 3 de agosto de 2026. He revisado toda la guía conforme a los cambios introducidos por ESPHome 2024.6, 2025.7 y 2026.1, además…

Continuar con este artículo

secrets.yaml en ESPHome: cómo proteger Wi-Fi, API y OTA

Descuentos en domótica SONOFF