ZimaOS heeft nu gedocumenteerde OpenAPI, maar de oude aanpak uit 2024 waarbij je /v1/users/login aanroept en het teruggegeven toegangstoken opnieuw gebruikt, moet worden beschouwd als een techniek voor sessieauthenticatie en niet als een systeem met permanente API-sleutels. IceWhale zei in die discussie expliciet dat permanente tokens niet werden ondersteund.
De huidige OpenAPI-documentatie richt zich op gegenereerde clients en service-eindpunten, niet op een interface voor persoonlijke toegangstokens. Houd voor automatisering zoals Home Assistant de authenticatie lokaal, stel het login-eindpunt niet openbaar bloot en zorg dat je integratie opnieuw kan authenticeren wanneer een sessietoken verloopt.
Gebruik de huidige OpenAPI-specificaties
De huidige ZimaOS OpenAPI-handleiding verwijst ontwikkelaars naar de OpenAPI-repository van IceWhale en toont gegenereerde clients voor opslag- en andere services.
Het historische login-eindpunt gaf een toegangstoken terug
In de brondiscussie slaagde de gebruiker erin om inloggegevens via POST naar /v1/users/login te sturen en vond die een toegangstoken in het antwoord. IceWhale zei vervolgens dat permanente tokens niet werden ondersteund.
Hardcodeer een tijdelijk token niet voor altijd
Een sessietoken kan verlopen of ongeldig worden gemaakt door wijzigingen in de login- of beveiligingsinstellingen. Sla inloggegevens of vernieuwde sessiestatus veilig op en handel authenticatiefouten expliciet af.
Houd de API op een vertrouwd netwerk
Stel interne ZimaOS API-eindpunten niet via port forwarding bloot aan het openbare internet. Maak eerst verbinding met de server via LAN, VPN of ZimaClient/privénetwerk.
Werk oude ZimaOS-versies bij voordat je met login-API's ontwikkelt
ZimaOS had tot en met versie 1.5.0 een kritiek probleem waarbij authenticatie kon worden omzeild, dat van invloed was op /v1/users/login; dit is verholpen in versie 1.5.3. Ontwikkel altijd met een actuele stabiele release.
Het ZimaOS-beveiligingsadvies over inloggen beschrijft die beveiligingsgrens.
Gebruik de minste rechten in Home Assistant
Als je temperatuur-, CPU-, stroom- of schijfgegevens verzamelt, vraag dan alleen de gegevens op die je integratie nodig heeft. Bouw geen automatisering die ook gebruikers, opslag of systeeminstellingen kan wijzigen, tenzij dat absoluut noodzakelijk is.
Houd rekening met wijzigingen in API-versies
De huidige gids verwijst naar versiegebonden servicepaden zoals /v2/local_storage. Ga er niet van uit dat elk endpoint uit 2024 voor altijd de aanbevolen interface blijft; genereer of werk clients bij op basis van actuele OpenAPI-schema's.
De gids voor privétoegang beschrijft het veiligere netwerkmodel.
Verwerk 401-reacties door opnieuw te authenticeren
Een robuuste integratie moet een HTTP 401-reactie of een melding van een verlopen sessie beschouwen als een signaal om een nieuwe sessie te verkrijgen, in plaats van steeds hetzelfde token opnieuw te proberen. Voeg een begrensde nieuwe poging toe, zodat een storing bij het inloggen niet tot een eindeloze aanvraaglus leidt.
Zet geen tokens in logboeken
Debuglogboeken van Home Assistant, shellgeschiedenis, schermafbeeldingen en Git-opslagplaatsen zijn veelvoorkomende plekken waar tokens kunnen uitlekken. Verwijder autorisatieheaders en JSON-reacties met inloggegevens voordat je diagnostische gegevens openbaar deelt.
Leg de API-contractversie vast waarvan je afhankelijk bent
Als je integratie gebruikmaakt van gegenereerde OpenAPI-clients, bewaar dan het schema en de versie bij je code en controleer wijzigingen upstream voordat je de clients opnieuw genereert. Zo zie je meteen wanneer een endpoint of de structuur van een reactie is gewijzigd, in plaats van dat automatiseringen onverwacht niet meer werken.
Veelgestelde vragen
Kan ZimaOS een permanent API-token genereren?
In de reactie van IceWhale stond dat permanente tokens niet werden ondersteund, en de huidige openbare documentatie beschrijft geen interface voor persoonlijke toegangstokens.
Hoe is het oude toegangstoken verkregen?
De forumgebruiker verkreeg deze na een geslaagde POST naar /v1/users/login.
Moet ik de API toegankelijk maken via internet?
Nee. Houd deze binnen een vertrouwd, particulier netwerk en authenticeer via een actuele, ondersteunde methode.
Kan ik een Home Assistant-integratie bouwen?
Ja, maar houd rekening met verlopen tokens, wijzigingen in API-versies en toegang met zo weinig mogelijk rechten.
