ZimaOS dispose désormais d’une documentation OpenAPI, mais l’ancienne méthode de 2024 consistant à appeler /v1/users/login et à réutiliser le jeton d’accès renvoyé doit être considérée comme une technique d’authentification par session, et non comme un système permanent de clés API. IceWhale a explicitement indiqué dans ce fil que les jetons permanents n’étaient pas pris en charge.
La documentation OpenAPI actuelle met l’accent sur les clients générés et les points de terminaison des services, plutôt que sur une interface de jetons d’accès personnels. Pour l’automatisation, notamment avec Home Assistant, gardez l’authentification locale, évitez d’exposer publiquement le point de terminaison de connexion et concevez votre intégration pour qu’elle se réauthentifie lorsqu’un jeton de session expire.
Utilisez les spécifications OpenAPI actuelles
Le guide OpenAPI de ZimaOS actuel renvoie les développeurs vers le dépôt OpenAPI d’IceWhale et présente des clients générés pour le stockage et d’autres services.
L’ancien point de terminaison de connexion renvoyait un jeton d’accès
Dans le fil d’origine, l’utilisateur a envoyé avec succès les identifiants à /v1/users/login et a trouvé un jeton d’accès dans la réponse. IceWhale a ensuite indiqué que les jetons permanents n’étaient pas pris en charge.
Ne codez pas définitivement un jeton temporaire en dur
Un jeton de session peut expirer ou être invalidé par des modifications de connexion ou de sécurité. Stockez les identifiants ou l’état de session actualisé de manière sécurisée et gérez explicitement les échecs d’authentification.
Gardez l’API sur un réseau de confiance
Ne redirigez pas les points de terminaison internes de l’API ZimaOS vers l’Internet public. Utilisez d’abord le réseau local, un VPN ou le réseau privé de ZimaClient pour accéder au serveur.
Mettez à jour les anciennes versions de ZimaOS avant de développer avec les API de connexion
ZimaOS présentait une vulnérabilité critique de contournement de l’authentification dans les versions jusqu’à la 1.5.0, affectant /v1/users/login ; elle a été corrigée dans la version 1.5.3. Développez toujours avec une version stable récente.
L’avis de sécurité concernant la connexion à ZimaOS documente cette limite de sécurité.
Appliquez le principe du moindre privilège dans Home Assistant
Si vous récupérez des mesures de température, de processeur, d’alimentation ou de disque, ne demandez que les données nécessaires à votre intégration. Évitez de créer une automatisation pouvant également modifier les utilisateurs, le stockage ou les paramètres système, sauf nécessité absolue.
Attendez-vous à une évolution des versions de l’API
Le guide actuel fait référence à des chemins de services versionnés tels que /v2/local_storage. Ne supposez pas que chaque point de terminaison de 2024 restera indéfiniment l’interface privilégiée ; générez ou mettez à jour vos clients à partir des schémas OpenAPI actuels.
Le guide d’accès privé présente un modèle réseau plus sûr.
Gérez les réponses 401 en vous réauthentifiant
Une intégration robuste doit considérer une réponse HTTP 401 ou une session expirée comme un signal indiquant qu’il faut obtenir une nouvelle session, plutôt que de réessayer indéfiniment avec le même jeton. Ajoutez une procédure de nouvelle tentative limitée afin qu’une panne de connexion ne crée pas une boucle infinie de requêtes.
Ne placez pas les jetons dans les journaux
Les journaux de débogage de Home Assistant, l’historique du shell, les captures d’écran et les dépôts Git sont des endroits courants où les jetons peuvent fuiter. Masquez les en-têtes d’autorisation et les réponses JSON de connexion avant de partager publiquement des informations de diagnostic.
Figez le contrat d’API dont vous dépendez
Si votre intégration utilise des clients OpenAPI générés, conservez le schéma et la version avec votre code et examinez les modifications en amont avant de régénérer les clients. Vous verrez ainsi clairement lorsqu’un point de terminaison ou la structure d’une réponse a changé, au lieu de provoquer une panne silencieuse des automatisations.
FAQ
ZimaOS peut-il générer un jeton API permanent ?
La réponse d’IceWhale dans la source indiquait que les jetons permanents n’étaient pas pris en charge, et la documentation publique actuelle ne décrit pas d’interface de jetons d’accès personnels.
Comment l’ancien jeton d’accès était-il obtenu ?
L’utilisateur du forum l’a obtenu après une requête POST réussie vers /v1/users/login.
Dois-je exposer l’API à Internet ?
Non. Gardez-la sur un réseau de confiance ou privé et utilisez un flux pris en charge actuellement pour vous authentifier.
Puis-je créer une intégration Home Assistant ?
Oui, mais prévoyez l’expiration des jetons, l’évolution des versions de l’API et un accès conforme au principe du moindre privilège.
