ZimaOS har nu dokumenterad OpenAPI, men det gamla mönstret från 2024 med att anropa /v1/users/login och återanvända den returnerade åtkomsttokenen bör ses som en metod för sessionsautentisering, inte som ett system med permanenta API-nycklar. IceWhale uppgav uttryckligen i den tråden att permanenta token inte stöddes.
Den aktuella OpenAPI-dokumentationen fokuserar på genererade klienter och tjänsteslutpunkter snarare än ett gränssnitt för personliga åtkomsttoken. För automatisering som Home Assistant bör autentiseringen ske lokalt, inloggningsslutpunkten inte exponeras offentligt och integrationen utformas så att den autentiserar sig på nytt när en sessionstoken löper ut.
Använd de aktuella OpenAPI-specifikationerna
Den aktuella ZimaOS OpenAPI-guiden hänvisar utvecklare till IceWhales OpenAPI-arkiv och visar genererade klienter för lagring och andra tjänster.
Den tidigare inloggningsslutpunkten returnerade en åtkomsttoken
I den ursprungliga tråden skickade användaren inloggningsuppgifter med POST till /v1/users/login och hittade en åtkomsttoken i svaret. IceWhale uppgav sedan att permanenta token inte stöddes.
Hårdkoda inte en tillfällig token för alltid
En sessionstoken kan löpa ut eller ogiltigförklaras av ändringar i inloggningen eller säkerhetsinställningarna. Lagra autentiseringsuppgifter eller uppdaterat sessionstillstånd säkert och hantera autentiseringsfel uttryckligen.
Håll API:et i ett betrott nätverk
Vidarebefordra inte interna ZimaOS API-slutpunkter till det offentliga internet. Använd LAN, VPN eller ZimaClient/privat nätverk för att först ansluta till servern.
Uppdatera äldre ZimaOS-versioner innan du utvecklar mot inloggnings-API:er
ZimaOS hade en kritisk autentiseringsbrist i versioner upp till och med 1.5.0 som påverkade /v1/users/login; den åtgärdades i 1.5.3. Utveckla alltid mot en aktuell stabil version.
ZimaOS säkerhetsmeddelande om inloggning beskriver den säkerhetsgränsen.
Använd principen om minsta möjliga behörighet i Home Assistant
Om du samlar in mätvärden för temperatur, CPU, strömförbrukning eller diskar bör du bara begära de data som integrationen behöver. Undvik att skapa automatiseringar som också kan ändra användare, lagring eller systeminställningar, om det inte är absolut nödvändigt.
Räkna med att API-versioner ändras
Den aktuella guiden hänvisar till versionshanterade tjänstesökvägar som /v2/local_storage. Utgå inte från att alla slutpunkter från 2024 fortsätter att vara det rekommenderade gränssnittet; generera eller uppdatera klienter utifrån aktuella OpenAPI-scheman.
Den privata åtkomstguiden beskriver en säkrare nätverksmodell.
Hantera 401-svar genom att autentisera på nytt
En robust integration bör behandla ett HTTP 401-svar eller en utgången session som en signal om att hämta en ny session, i stället för att upprepade gånger försöka med samma token. Lägg till ett begränsat antal återförsök så att ett avbrott i inloggningen inte skapar en oändlig begärandeloop.
Lägg inte token i loggar
Felsökningsloggar från Home Assistant, kommandohistorik, skärmbilder och Git-arkiv är vanliga platser där token läcker ut. Maskera auktoriseringshuvuden och JSON-inloggningssvar innan du delar diagnostik offentligt.
Lås fast API-kontraktet som du förlitar dig på
Om din integration använder genererade OpenAPI-klienter bör du spara schemat och versionen tillsammans med koden och granska ändringar uppströms innan du genererar om klienterna. Då märker du direkt om en slutpunkt eller svarsstruktur har ändrats, i stället för att automatiseringar går sönder utan förvarning.
Vanliga frågor
Kan ZimaOS generera en permanent API-token?
I det ursprungliga svaret från IceWhale stod det att permanenta token inte stöddes, och den aktuella offentliga dokumentationen beskriver inte något gränssnitt för personliga åtkomsttoken.
Hur fick man den gamla åtkomsttokenen?
Forumanvändaren fick det efter en lyckad POST till /v1/users/login.
Bör jag exponera API:et för internet?
Nej. Använd ett betrott/privat nätverk och autentisera via ett aktuellt, officiellt stödt flöde.
Kan jag skapa en Home Assistant-integration?
Ja, men utforma den med hänsyn till att token går ut, API-versioner ändras och åtkomst ska begränsas till minsta möjliga behörighet.
