ZimaOS heeft nu gedocumenteerde OpenAPI-documentatie, maar het oude patroon uit 2024 waarbij je /v1/users/login aanroept en het verkregen toegangstoken hergebruikt, moet worden beschouwd als een techniek voor sessieauthenticatie en niet als een permanent API-keysysteem. IceWhale gaf in die thread expliciet aan 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, voorkom dat het login-eindpunt openbaar wordt gemaakt en ontwerp je integratie zo dat deze zich opnieuw authenticeert wanneer een sessietoken verloopt.
Gebruik de huidige OpenAPI-specificaties
De huidige ZimaOS OpenAPI-handleiding verwijst ontwikkelaars naar IceWhale's OpenAPI-repository en toont gegenereerde clients voor opslag en andere services.
Het historische login-eindpunt gaf een toegangstoken terug
In de oorspronkelijke thread plaatste de gebruiker met succes de inloggegevens via POST naar /v1/users/login en vond een toegangstoken in de respons. IceWhale gaf vervolgens aan 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
Stuur interne ZimaOS-API-eindpunten niet door naar het openbare internet. Gebruik eerst een LAN, VPN of ZimaClient/privénetwerk om de server te bereiken.
Werk oude ZimaOS-builds bij voordat je login-API's ontwikkelt
ZimaOS had in versies tot en met 1.5.0 een kritiek probleem waarbij authenticatie kon worden omzeild, met gevolgen voor /v1/users/login; dit werd opgelost in 1.5.3. Ontwikkel altijd tegen een actuele stabiele release.
Het ZimaOS-beveiligingsadvies voor login documenteert die beveiligingsgrens.
Gebruik minimale toegangsrechten in Home Assistant
Als je temperatuur-, CPU-, stroom- of schijfstatistieken verzamelt, vraag dan alleen de gegevens op die je integratie nodig heeft. Vermijd automatisering die ook gebruikers, opslag of systeeminstellingen kan wijzigen, tenzij dat absoluut noodzakelijk is.
Houd rekening met wijzigingen in API-versies
De huidige handleiding verwijst naar versiegebonden servicepaden zoals /v2/local_storage. Ga er niet van uit dat elk eindpunt uit 2024 voor altijd de aanbevolen interface blijft; genereer of werk clients bij op basis van de huidige OpenAPI-schema's.
De handleiding voor priv toegang biedt het veiligere netwerkmodel.
Verwerk 401-responses door je opnieuw te authenticeren
Een robuuste integratie moet een HTTP 401- of verlopen-sessie-respons behandelen als een signaal om een nieuwe sessie te verkrijgen, in plaats van hetzelfde token steeds opnieuw te proberen. Voeg een begrensd herhaalpad toe, zodat een loginstoring geen eindeloze aanvraaglus veroorzaakt.
Zet tokens niet in logboeken
Debuglogboeken van Home Assistant, shellgeschiedenis, schermafbeeldingen en Git-repositories zijn veelvoorkomende plekken waar tokens kunnen uitlekken. Maskeer autorisatieheaders en JSON-loginresponses voordat je diagnostische gegevens openbaar deelt.
Leg het API-contract vast waarvan je afhankelijk bent
Als je integratie gegenereerde OpenAPI-clients gebruikt, bewaar het schema en de versie samen met je code en controleer wijzigingen upstream voordat je opnieuw genereert. Zo is duidelijk wanneer een eindpunt of responsstructuur is gewijzigd, in plaats van dat automatiseringen stilzwijgend uitvallen.
Veelgestelde vragen
Kan ZimaOS een permanent API-token genereren?
In het antwoord van IceWhale in de bron stond dat permanente tokens niet werden ondersteund, en de huidige openbare documentatie beschrijft geen interface voor persoonlijke toegangstokens.
Hoe werd het oude toegangstoken verkregen?
De forumgebruiker verkreeg het na een geslaagde POST naar /v1/users/login.
Moet ik de API openbaar maken op internet?
Nee. Houd deze binnen een vertrouwd of privénetwerk en authenticeer via een actuele, ondersteunde methode.
Kan ik een Home Assistant-integratie bouwen?
Ja, maar ontwerp deze met aandacht voor het verlopen van tokens, wijzigingen in API-versies en minimale toegangsrechten.
