Actualizado el 22 de enero de 2026
En el ecosistema de Home Assistant, la seguridad de nuestros datos más sensibles es una prioridad absoluta. Si buscas una configuración segura en Home Assistant, el archivo secrets.yaml no es solo un amigo, es tu principal aliado. Este fichero, aunque veterano, sigue siendo en 2026 la piedra angular para almacenar información crítica como contraseñas, tokens de acceso y API keys fuera de tu configuración principal (configuration.yaml), evitando así su exposición accidental.
¿Qué es y por qué sigue siendo crucial `secrets.yaml` en 2026?
Imagina que quieres compartir una de tus fantásticas automatizaciones con la comunidad, pero esta incluye la contraseña de tu broker MQTT o la API key de un servicio meteorológico. Si estuviera directamente en tu archivo configuration.yaml, tendrías que acordarte de borrarla antes de compartir, un proceso propenso a errores que podría exponer tus credenciales.
El archivo secrets.yaml resuelve este problema de raíz. Funciona como una caja fuerte digital donde guardas cada dato sensible bajo un nombre (o «clave»). Luego, desde cualquier otro archivo de configuración, en lugar de escribir la contraseña real, simplemente «llamas» a esa clave. Home Assistant se encarga de sustituir la llamada por el valor real de forma interna, sin que nunca sea visible.
Las ventajas principales son:
- Seguridad: Es el método más eficaz para proteger las API keys en Home Assistant y otras credenciales.
- Portabilidad: Puedes compartir tus archivos de configuración de forma segura, ya que los secretos no viajan con ellos.
- Mantenimiento Centralizado: Si una contraseña o token cambia, solo tienes que actualizarlo en un único lugar:
secrets.yaml.
Cómo Configurar tu Archivo `secrets.yaml` Paso a Paso
Configurar este archivo es un proceso sencillo que te aportará una capa de seguridad fundamental. El fichero se encuentra en la misma carpeta que tu configuration.yaml, normalmente /config/.
- Accede a tus archivos: La forma más recomendada en 2026 es a través del Add-on «Studio Code Server» (anteriormente conocido como Visual Studio Code). Si no lo tienes, instálalo desde la tienda de Add-ons de Home Assistant. Ofrece una experiencia de edición muy superior al editor de archivos básico.
- Crea el archivo (si no existe): Dentro de la carpeta
/config, haz clic derecho y selecciona «Nuevo Archivo». Nómbralo exactamentesecrets.yaml. - Añade tus secretos: La estructura es simple:
nombre_del_secreto: valor_del_secreto. Cada secreto debe ir en una nueva línea. Es crucial no usar tabulaciones, solo espacios, como en todo archivo YAML.
Por ejemplo, si quieres guardar un token de acceso y una contraseña:
# Ejemplo de archivo secrets.yaml en 2026
mi_token_de_acceso: "abcdef1234567890"
mi_password_wifi: "P4s$w0rd_S3gur4!"
api_key_openweathermap: "987654321fedcba0987654321fedcba"
Cómo Usar los Secretos con `!secret` en Home Assistant
Una vez definidos tus secretos, usarlos en tu configuration.yaml o en otros archivos de configuración es muy intuitivo gracias a la directiva !secret.
Siguiendo el ejemplo anterior, si una integración te pide la API Key, la configuración se vería así:
# En configuration.yaml
weather:
- platform: openweathermap
api_key: !secret api_key_openweathermap
Cuando Home Assistant carga esta configuración, ve !secret api_key_openweathermap y automáticamente lo reemplaza por el valor "987654321fedcba0987654321fedcba" que tiene guardado en secrets.yaml. ¡Así de simple y seguro!
`secrets.yaml` vs. Gestión desde la Interfaz de Usuario (UI)
Con los años, Home Assistant ha evolucionado para permitir configurar muchas integraciones directamente desde la interfaz gráfica, que a su vez gestiona los secretos internamente. Aunque esto es más sencillo para los recién llegados, gestionar contraseñas en Home Assistant a través de secrets.yaml sigue ofreciendo ventajas clave para usuarios intermedios y avanzados.
| Característica | secrets.yaml (Edición YAML) | Gestión por Interfaz de Usuario (UI) |
|---|---|---|
| Facilidad de Uso | Requiere edición manual de archivos. Curva de aprendizaje inicial. | Muy sencillo. Campos de texto y botones en la web. Ideal para principiantes. |
| Versionado y Backup | Excelente. Se puede incluir en backups de Git (con .gitignore) o copias de seguridad estándar como Google Drive. | Los secretos se guardan en el directorio .storage, que es más opaco y difícil de gestionar manualmente. Depende de los snapshots completos. |
| Compartir Configuración | Ideal. Puedes compartir todo tu configuration.yaml sin riesgo de exponer datos sensibles. | Imposible compartir la configuración de una integración sin reconfigurarla manualmente en el otro sistema. |
| Soporte | Compatible con casi todas las integraciones que se configuran vía YAML. | Limitado a las integraciones que han sido migradas al flujo de configuración por UI. |
Ejemplos Prácticos Avanzados para 2026
Veamos cómo aplicar secrets.yaml en escenarios más complejos que demuestran su verdadero poder.
Ejemplo 1: Proteger la API Key de un Sensor RESTful
Supongamos que quieres crear un sensor que obtiene el precio de una criptomoneda desde una API que requiere autenticación con un «Bearer Token».
En tu archivo secrets.yaml:
crypto_api_token: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
En tu archivo de sensores (o configuration.yaml):
rest:
- resource: "https://api.crypto-service.com/v1/price/btc-eur"
scan_interval: 300
headers:
Authorization: !secret crypto_api_token
Content-Type: "application/json"
sensor:
- name: "Precio BTC"
value_template: "{{ value_json.price }}"
unit_of_measurement: "EUR"
Ejemplo 2: Configuración Segura para Zigbee2MQTT
Al configurar la integración de MQTT para conectar con un broker como el que se usa en Zigbee2MQTT en Home Assistant 2026, es vital proteger el usuario y la contraseña.
En tu archivo secrets.yaml:
mqtt_broker_address: "192.168.1.50"
mqtt_username: "ha-user"
mqtt_password: "super_secret_password_123"
Al configurar la integración MQTT en configuration.yaml:
mqtt:
broker: !secret mqtt_broker_address
username: !secret mqtt_username
password: !secret mqtt_password
La Regla de Oro: `secrets.yaml` y `.gitignore`
Si eres un usuario que versiona su configuración de Home Assistant usando Git y la sube a repositorios públicos como GitHub (una práctica excelente para tener un backup y control de cambios), hay un paso que NO puedes saltarte: ignorar el archivo secrets.yaml.
El archivo .gitignore le dice a Git qué archivos o carpetas debe ignorar y no subir al repositorio. Si no incluyes secrets.yaml aquí, estarás publicando todas tus contraseñas y tokens en internet.
Para evitarlo, simplemente crea un archivo llamado .gitignore en tu carpeta /config y añade la siguiente línea:
# Ignorar el archivo de secretos
secrets.yaml
Con esto, garantizas que tu configuración se comparte, pero tus secretos permanecen seguros en tu sistema local. Es una de las mejores prácticas para una gestión segura de tu red doméstica.
Errores Comunes y Soluciones («Secret not found»)
El error más habitual al trabajar con este sistema es el temido mensaje "Secret [nombre_del_secreto] not found" en los registros de Home Assistant. Aquí te dejo las causas más comunes y cómo solucionarlas:
- Error tipográfico: Revisa que el nombre del secreto en
secrets.yamly el nombre que llamas con!secretsean exactamente iguales, mayúsculas y minúsculas incluidas. - Falta de reinicio: Home Assistant solo lee el archivo
secrets.yamlal arrancar. Si has añadido un nuevo secreto, debes reiniciar Home Assistant para que lo reconozca. Con ir a «Herramientas de desarrollador» -> «YAML» y pulsar «Reiniciar» es suficiente. - Formato YAML incorrecto: Asegúrate de que en
secrets.yamlcada entrada sigue el formatoclave: valory no hay tabulaciones, solo espacios. Un error de indentación puede hacer que el archivo no se lea correctamente. - Archivo no guardado: Parece obvio, pero a veces olvidamos guardar los cambios en el editor antes de reiniciar. ¡Verifícalo!
En resumen, aunque Home Assistant avanza hacia una gestión más visual, el archivo secrets.yaml sigue siendo en 2026 una herramienta indispensable para cualquier usuario que se tome en serio la seguridad y la gestión ordenada de su hogar inteligente. Dominarlo es un paso fundamental para llevar tu configuración al siguiente nivel de profesionalidad y robustez.