ZimaOS ahora cuenta con una OpenAPI documentada, pero el patrón 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 sesión, no un sistema permanente de claves API. IceWhale afirmó explícitamente en ese hilo que no se admitían tokens permanentes.
La documentación actual de OpenAPI se centra en clientes generados y endpoints de servicios, no en una interfaz de tokens de acceso personal. Para automatizaciones como Home Assistant, mantén la autenticación local, evita exponer públicamente el endpoint de inicio de sesión y diseña la integración para volver a autenticarse cuando expire el token de sesión.
Usa las especificaciones actuales de OpenAPI
La guía de OpenAPI de ZimaOS actual dirige a los desarrolladores al repositorio de OpenAPI de IceWhale y muestra clientes generados para el almacenamiento y otros servicios.
El endpoint histórico de inicio de sesión devolvía un token de acceso
En el hilo original, el usuario hizo correctamente un POST de sus credenciales a /v1/users/login y encontró un token de acceso en la respuesta. IceWhale indicó entonces que no se admitían tokens permanentes.
No codifiques un token temporal para siempre
Un token de sesión puede caducar o invalidarse debido a cambios de inicio de sesión o de seguridad. Almacena las credenciales o el estado de sesión renovado de forma segura y gestiona explícitamente los fallos de autenticación.
Mantén la API en una red de confianza
No redirijas mediante port forwarding los endpoints internos de la API de ZimaOS a Internet pública. Usa la LAN, una VPN o ZimaClient/redes privadas para conectarte primero al servidor.
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 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.
Aplica el principio de mínimo privilegio en Home Assistant
Si recopilas métricas de temperatura, CPU, energía o disco, solicita únicamente 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.
Espera cambios en las versiones de la API
La guía actual hace referencia a rutas de servicio versionadas, como /v2/local_storage. No des por hecho que todos los endpoints de 2024 seguirán siendo la interfaz recomendada indefinidamente; genera o actualiza los clientes a partir de los esquemas OpenAPI actuales.
La guía de acceso privado proporciona un modelo de red más seguro.
Gestiona las respuestas 401 volviendo a autenticarte
Una integración sólida debe tratar una respuesta HTTP 401 o de sesión caducada como una señal para obtener una sesión nueva, en lugar de reintentar repetidamente con el mismo token. Añade una ruta de reintento limitada para que una interrupción del inicio de sesión no cree 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 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 utiliza clientes OpenAPI generados, conserva el esquema y la versión junto con tu código, y revisa los cambios ascendentes antes de volver a generarlos. Así será evidente cuándo cambia un endpoint o la estructura de una respuesta, en lugar de que las automatizaciones fallen silenciosamente.
Preguntas frecuentes
¿Puede ZimaOS generar un token API permanente?
La respuesta original de IceWhale indicaba que no se admitían tokens permanentes, y la documentación pública actual no documenta ninguna interfaz de tokens de acceso personal.
¿Cómo se obtuvo el antiguo token de acceso?
El usuario del foro lo obtuvo después de realizar correctamente un POST a /v1/users/login.
¿Debería exponer la API a Internet?
No. Mantenla en una red privada o de confianza y autentícate mediante un flujo compatible actual.
¿Puedo crear una integración para Home Assistant?
Sí, pero diséñala teniendo en cuenta la caducidad de los tokens, los cambios de versión de la API y el acceso con privilegios mínimos.
