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

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

Cuando empezamos con ESPHome es habitual escribir el nombre y la contraseña de la red Wi‑Fi directamente en cada archivo YAML. También terminamos repitiendo claves de API, contraseñas OTA, credenciales MQTT y usuarios del servidor web. Funciona, pero es una mala costumbre cuando el proyecto crece o cuando queremos compartir el código.

ESPHome ofrece una solución sencilla: guardar los valores sensibles en un archivo llamado secrets.yaml y referenciarlos desde la configuración con !secret. En esta guía explico cómo funciona, qué debe guardarse ahí, qué no protege y cómo organizarlo en una instalación con varios dispositivos.

Qué es exactamente secrets.yaml

secrets.yaml es un archivo YAML que ESPHome busca junto al archivo de configuración del dispositivo. Contiene un mapa plano de nombres y valores escalares. Por ejemplo:

wifi_ssid: "MiRed"
wifi_password: "una-contraseña-larga"
api_key_salon: "CLAVE_BASE64"

En el archivo del dispositivo se utiliza la etiqueta especial !secret:

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

Durante la validación y compilación, ESPHome resuelve la referencia y utiliza el valor correspondiente. El nombre de la clave no tiene por qué coincidir con el nombre del dispositivo, pero debe escribirse exactamente igual.

Por qué es recomendable utilizarlo

La ventaja principal es separar configuración y credenciales. El YAML del dispositivo puede compartirse, versionarse o publicarse sin revelar la contraseña de la red. También evita copiar una contraseña en diez archivos y tener que localizar cada aparición cuando cambia.

Es especialmente útil si utilizas Git, copias de seguridad, paquetes compartidos, repositorios privados o colaboras con otra persona. Aun así, secrets.yaml no cifra el contenido: cualquiera que pueda leer ese archivo puede leer las credenciales.

Qué valores conviene guardar

• SSID y contraseña Wi‑Fi.
• Claves de cifrado de la API nativa de ESPHome.
• Contraseñas OTA cuando todavía se utilizan.
• Claves de cifrado OTA en configuraciones que las requieran.
• Contraseñas de un punto de acceso de fallback.
• Usuarios y contraseñas de MQTT.
• Contraseña de autenticación de web_server.
• Tokens o credenciales de servicios externos.

Ejemplo completo para un dispositivo

El archivo del dispositivo mantiene la estructura y solo referencia secretos:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
api:
  encryption:
    key: !secret salon_api_key
ota:
  - platform: esphome
    password: !secret salon_ota_password
web_server:
  auth:
    username: admin
    password: !secret salon_web_password

Y secrets.yaml contiene los valores:

wifi_ssid: "MiRed"
wifi_password: "contraseña-wifi"
salon_api_key: "clave-api-unica-del-salon"
salon_ota_password: "contraseña-ota-unica"
salon_web_password: "contraseña-web-unica"

Una clave de API por dispositivo

No reutilices la misma clave de cifrado de API en todos los ESP32. Cada dispositivo debería tener una clave única, por ejemplo salon_api_key, cocina_api_key y pluja_api_key. Así, si un dispositivo queda comprometido, no tienes que considerar comprometidos todos los demás.

La contraseña Wi‑Fi sí puede ser común porque pertenece a la red, pero las claves de cifrado y las contraseñas de administración deberían ser únicas por dispositivo.

API, OTA y web_server no son lo mismo

La API nativa permite que Home Assistant se comunique con el dispositivo. La clave de cifrado protege esa comunicación. OTA permite actualizar el firmware. Una contraseña OTA autentica la actualización, pero en las versiones actuales es preferible utilizar cifrado OTA cuando esté disponible. El servidor web es otra superficie independiente: si lo activas, protégelo con autenticación o desactívalo si no lo necesitas.

El punto de acceso de fallback

Si el dispositivo no conecta al Wi‑Fi puede crear una red de emergencia. Esa red no debe quedar abierta:

wifi:
  ap:
    ssid: "Salon Fallback"
    password: !secret salon_ap_password

Una contraseña guardada en secrets.yaml evita publicarla en el YAML, pero no sustituye a una contraseña fuerte ni a una red doméstica bien protegida.

MQTT y credenciales externas

Si utilizas MQTT en lugar de la API nativa, guarda el broker, usuario y contraseña:

mqtt:
  broker: !secret mqtt_broker
  username: !secret dispositivo_mqtt_user
  password: !secret dispositivo_mqtt_password

Siempre que sea posible, utiliza autenticación, TLS y credenciales separadas por dispositivo o función.

Qué no debe ir en secrets.yaml

No hace falta ocultar el nombre del dispositivo, el GPIO, el modelo de placa, el nombre público del sensor o la configuración normal de un componente. Guardar todo en secrets.yaml dificulta el mantenimiento. Utilízalo para valores que realmente conceden acceso o contienen información privada.

secrets.yaml no es cifrado

Esta distinción es fundamental. secrets.yaml es un archivo de texto plano. Protege frente a publicar accidentalmente una contraseña junto al código, pero no protege el archivo si alguien accede al sistema, a una copia de seguridad o al repositorio.

Usa permisos adecuados, copias de seguridad protegidas y evita mostrar el archivo en capturas o tutoriales. Si una credencial se filtra, no basta con moverla de sitio: hay que cambiarla o revocarla.

Git y .gitignore

Si el directorio de ESPHome está versionado, añade el archivo al .gitignore:

secrets.yaml
*.backup

Comprueba que no estuviera versionado antes. Si ya se publicó, eliminarlo del último commit no basta: hay que rotar las contraseñas y limpiar el historial del repositorio.

Compartir secretos con Home Assistant

ESPHome puede incluir el archivo de secretos de Home Assistant si quieres mantener una única fuente, por ejemplo con <<: !include ../secrets.yaml en el directorio de ESPHome. Hazlo solo si entiendes la estructura de carpetas y si ambos proyectos comparten una política de copias de seguridad. Separar los archivos suele ser más fácil de mantener.

Errores habituales

Secret not found

Comprueba que el archivo se llama exactamente secrets.yaml, está en el directorio esperado y la clave está escrita igual. Revisa también la indentación.

El valor contiene caracteres especiales

Rodea contraseñas complejas con comillas. Evita modificar espacios, dos puntos o símbolos al copiar una clave.

La configuración valida pero el dispositivo no conecta

Que ESPHome resuelva el secreto no significa que la contraseña sea correcta. Comprueba el SSID, la contraseña, el alcance Wi‑Fi, el modo de autenticación y los registros del dispositivo.

Buenas prácticas resumidas

1. Usa !secret para valores sensibles.
2. No subas secrets.yaml a Git.
3. Utiliza claves API únicas por dispositivo.
4. Protege OTA, web_server y fallback AP.
5. No confundas ocultar un secreto con cifrarlo.
6. Rota credenciales cuando sospeches que se han filtrado.
7. Conserva una copia segura y prueba la restauración.

Conclusión

secrets.yaml es una de las primeras costumbres que merece la pena adoptar en ESPHome. No añade funciones al sensor, pero evita que las credenciales queden dispersas por todos los archivos y reduce mucho el riesgo de publicarlas por accidente.

La combinación correcta es sencilla: !secret para separar valores sensibles, Git para el código sin secretos, claves únicas por dispositivo y cifrado o autenticación en las comunicaciones que lo necesiten.

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↓