ZimaOS har nu ett dokumenterat OpenAPI, men det gamla mönstret från 2024 med att anropa /v1/users/login och återanvända den returnerade åtkomsttoken bör betraktas som en teknik för sessionsautentisering, inte som ett system med permanenta API-nycklar. IceWhale sade uttryckligen i den tråden att permanenta token inte stöddes.
Den aktuella OpenAPI-dokumentationen fokuserar på genererade klienter och tjänsteendpoints snarare än ett gränssnitt för personliga åtkomsttoken. För automatisering, exempelvis Home Assistant, bör du hålla autentiseringen lokal, undvika att exponera inloggningsendpointen offentligt och utforma integrationen så att den autentiserar på nytt när en sessionstoken löper ut.
Använd de aktuella OpenAPI-specifikationerna
Den aktuella OpenAPI-guiden för ZimaOS hänvisar utvecklare till IceWhales OpenAPI-arkiv och visar genererade klienter för lagring och andra tjänster.
Den historiska inloggningsendpointen 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 sade därefter 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 inloggning eller säkerhetsinställningar. Lagra inloggningsuppgifter eller förnyat sessionstillstånd säkert och hantera autentiseringsfel uttryckligen.
Håll API:t på ett betrott nätverk
Vidarebefordra inte interna ZimaOS-API-endpoints till det offentliga internet. Använd LAN, VPN eller ZimaClient/privat nätverk för att först nå servern.
Uppdatera gamla ZimaOS-versioner innan du utvecklar mot inloggnings-API:er
ZimaOS hade ett kritiskt problem med kringgående av autentisering i versioner upp till och med 1.5.0 som påverkade /v1/users/login; det åtgärdades i 1.5.3. Utveckla alltid mot en aktuell stabil version.
Säkerhetsmeddelandet om ZimaOS-inloggning beskriver denna säkerhetsgräns.
Använd minsta möjliga behörighet i Home Assistant
Om du samlar in temperatur-, CPU-, ström- eller diskmätvärden bör du bara begära de uppgifter som integrationen behöver. Undvik att bygga automatisering som även 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 versionsnumrerade tjänstesökvägar som /v2/local_storage. Utgå inte från att varje endpoint från 2024 förblir det rekommenderade gränssnittet för alltid; generera eller uppdatera klienter från aktuella OpenAPI-scheman.
Den privata åtkomstguiden beskriver den säkrare nätverksmodellen.
Hantera 401-svar genom att autentisera på nytt
En robust integration bör behandla ett HTTP 401-svar eller en signal om att sessionen har löpt ut som en indikation på att en ny session ska hämtas, i stället för att upprepade gånger försöka med samma token. Lägg till en begränsad omförsöksväg så att ett inloggningsavbrott inte skapar en oändlig begärandeloop.
Placera inte token i loggar
Home Assistants felsökningsloggar, skalmhistorik, skärmbilder och Git-arkiv är vanliga platser där token kan läcka. Maskera auktoriseringshuvuden och JSON-svar från inloggningar innan du delar felsökningsinformation offentligt.
Lås det API-kontrakt du är beroende av
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 klienten. Då blir det tydligt när en endpoint eller svarsstruktur har ändrats, i stället för att automatiseringar går sönder i tysthet.
Vanliga frågor
Kan ZimaOS generera en permanent API-token?
IceWhales svar i källan sade att permanenta token inte stöddes, och den aktuella offentliga dokumentationen beskriver inte något gränssnitt för personliga åtkomsttoken.
Hur hämtades den gamla åtkomsttoken?
Forumanvändaren hämtade den efter en lyckad POST-begäran till /v1/users/login.
Bör jag exponera API:t på internet?
Nej. Håll det på ett betrott eller privat nätverk och autentisera via ett aktuellt, stödd flöde.
Kan jag bygga en Home Assistant-integration?
Ja, men utforma den med hänsyn till att token kan löpa ut, att API-versioner kan ändras och att åtkomsten ska följa principen om minsta möjliga behörighet.
