ZimaOS ya cuenta con una OpenAPI documentada, pero el método antiguo de 2024 de llamar a /v1/users/login y reutilizar el token de acceso devuelto debe considerarse una técnica de autenticación de sesiones, no un sistema de claves de API permanentes. En ese hilo, IceWhale dijo explícitamente que no admitía tokens permanentes.
La documentación actual de OpenAPI se centra en los clientes generados y los endpoints de servicios, no en una interfaz de tokens de acceso personales. Para automatizaciones como Home Assistant, mantén la autenticación en local, evita exponer públicamente el endpoint de inicio de sesión y diseña la integración para que vuelva a autenticarse cuando caduque un token de sesión.
Usa las especificaciones actuales de OpenAPI
La guía actual de OpenAPI de ZimaOS dirige a los desarrolladores al repositorio de OpenAPI de IceWhale y muestra clientes generados para almacenamiento y otros servicios.
El endpoint de inicio de sesión histórico devolvía un token de acceso
En el hilo original, el usuario logró enviar credenciales mediante POST a /v1/users/login y encontró un token de acceso en la respuesta. Luego, IceWhale dijo que no admitía tokens permanentes.
No codifiques permanentemente un token temporal
Un token de sesión puede caducar o invalidarse por cambios en el inicio de sesión o la seguridad. Guarda de forma segura las credenciales o el estado de sesión renovado y gestiona explícitamente los fallos de autenticación.
Mantén la API en una red de confianza
No redirijas los puertos de los endpoints internos de la API de ZimaOS a Internet. Primero, accede al servidor a través de la LAN, una VPN o la red privada de ZimaClient.
Actualiza las versiones antiguas de ZimaOS antes de desarrollar con las API de inicio de sesión
ZimaOS tenía un problema crítico de omisión de autenticación en las versiones hasta la 1.5.0, que afectaba a /v1/users/login; se corrigió en la versión 1.5.3. Desarrolla siempre con una versión estable actual.
El aviso de seguridad sobre el inicio de sesión de ZimaOS documenta ese límite de seguridad.
Usa el principio de privilegios mínimos en Home Assistant
Si recopilas métricas de temperatura, CPU, consumo eléctrico o discos, solicita solo los datos que necesite tu integración. Evita crear automatizaciones que también puedan modificar usuarios, almacenamiento o ajustes del sistema, salvo que sea absolutamente necesario.
Ten en cuenta que las versiones de la API pueden cambiar
La guía actual hace referencia a rutas de servicio versionadas, como /v2/local_storage. No des por sentado que todos los endpoints de 2024 seguirán siendo la interfaz preferida indefinidamente; genera o actualiza los clientes a partir de los esquemas OpenAPI actuales.
La guía de acceso privado describe el modelo de red más seguro.
Vuelve a autenticarte cuando recibas respuestas 401
Una integración robusta debería tratar una respuesta HTTP 401 o de sesión caducada como una señal para obtener una sesión nueva, en lugar de volver a intentar repetidamente con el mismo token. Añade un mecanismo de reintentos limitado para evitar que una interrupción del inicio de sesión provoque un bucle infinito de solicitudes.
No incluyas tokens en los registros
Los registros de depuración de Home Assistant, el historial del shell, las capturas de pantalla y los repositorios de Git son lugares habituales donde pueden filtrarse los tokens. Oculta los encabezados de autorización y las respuestas JSON de inicio de sesión antes de compartir diagnósticos públicamente.
Fija el contrato de API del que dependes
Si tu integración usa clientes de OpenAPI generados, conserva el esquema y la versión junto con tu código y revisa los cambios anteriores antes de volver a generarlos. Así podrás detectar fácilmente si ha cambiado un endpoint o la estructura de una respuesta, en lugar de que las automatizaciones dejen de funcionar sin previo aviso.
Preguntas frecuentes
¿Puede ZimaOS generar un token de API permanente?
La respuesta original de IceWhale en el foro decía que no se admitían tokens permanentes, y la documentación pública actual no explica cómo obtener un token de acceso personal desde la interfaz.
¿Cómo se obtuvo el antiguo token de acceso?
El usuario del foro lo obtuvo tras una solicitud POST exitosa a /v1/users/login.
¿Debería exponer la API a Internet?
No. Limítala a una red de confianza o privada y autentícate mediante un flujo compatible actualmente.
¿Puedo crear una integración con Home Assistant?
Sí, pero diseña teniendo en cuenta la caducidad de los tokens, los cambios de versión de la API y el acceso con los mínimos privilegios.
