ZimaOS에는 이제 문서화된 OpenAPI가 있지만, /v1/users/login을 호출하고 반환된 액세스 토큰을 재사용하는 2024년의 이전 방식은 영구 API 키 시스템이 아닌 세션 인증 기법으로 취급해야 합니다. IceWhale은 해당 스레드에서 영구 토큰을 지원하지 않는다고 명시적으로 밝혔습니다.
현재 OpenAPI 문서는 개인용 액세스 토큰 UI보다 생성된 클라이언트와 서비스 엔드포인트에 초점을 맞춥니다. Home Assistant와 같은 자동화를 위해 인증은 로컬에서 처리하고 로그인 엔드포인트를 공개적으로 노출하지 않으며 세션 토큰 만료 시 다시 인증하도록 연동을 설계하세요.
최신 OpenAPI 사양 사용하기
현재 ZimaOS OpenAPI 가이드는 개발자에게 IceWhale의 OpenAPI 저장소를 안내하고 스토리지 및 기타 서비스용으로 생성된 클라이언트를 보여 줍니다.
과거 로그인 엔드포인트는 액세스 토큰을 반환했습니다
원본 스레드에서 사용자는 /v1/users/login으로 자격 증명을 성공적으로 POST하고 응답에서 액세스 토큰을 찾았습니다. 이후 IceWhale은 영구 토큰은 지원되지 않는다고 밝혔습니다.
임시 토큰을 영구적으로 하드코딩하지 마세요
세션 토큰은 만료되거나 로그인/보안 설정 변경으로 무효화될 수 있습니다. 자격 증명이나 갱신된 세션 상태를 안전하게 저장하고 인증 실패를 명시적으로 처리하세요.
신뢰할 수 있는 네트워크에서 API 사용하기
내부 ZimaOS API 엔드포인트를 포트 포워딩으로 공용 인터넷에 노출하지 마세요. 먼저 LAN, VPN 또는 ZimaClient/프라이빗 네트워킹을 통해 서버에 접속하세요.
로그인 API를 대상으로 개발하기 전에 오래된 ZimaOS 빌드를 업데이트하세요
ZimaOS 1.5.0 이하 버전에는 심각한 인증 우회 취약점이 있었으며, 이 취약점은 /v1/users/login에 영향을 미쳤고 1.5.3에서 패치되었습니다. 항상 최신 안정 버전을 기준으로 개발하세요.
ZimaOS 로그인 보안 권고에 해당 보안 경계가 명시되어 있습니다.
Home Assistant에서 최소 권한 사용하기
온도, CPU, 전력 또는 디스크 메트릭을 수집한다면 연동에 필요한 데이터만 요청하세요. 꼭 필요한 경우가 아니라면 사용자, 스토리지 또는 시스템 설정도 변경할 수 있는 자동화는 만들지 마세요.
API 버전이 변경될 수 있음을 고려하세요
현재 가이드에서는 /v2/local_storage와 같은 버전이 포함된 서비스 경로를 안내합니다. 모든 2024년 엔드포인트가 앞으로도 계속 권장되는 인터페이스라고 단정하지 마세요. 최신 OpenAPI 스키마를 바탕으로 클라이언트를 생성하거나 업데이트하세요.
더 안전한 네트워크 구성은 비공개 액세스 가이드를 참고하세요.
401 응답을 받으면 다시 인증하세요
안정적인 연동이라면 HTTP 401 또는 세션 만료 응답이 오면 같은 토큰으로 계속 재시도하지 말고 새 세션을 받아야 합니다. 로그인 장애가 끝없는 요청 루프를 일으키지 않도록 재시도 횟수를 제한하세요.
로그에 토큰을 넣지 마세요
Home Assistant 디버그 로그, 셸 기록, 스크린샷, Git 저장소는 토큰이 유출되기 쉬운 곳입니다. 진단 정보를 공개적으로 공유하기 전에 인증 헤더와 JSON 로그인 응답에서 민감한 정보를 가리세요.
의존하는 API 계약 버전을 고정하세요
연동에 생성된 OpenAPI 클라이언트를 사용한다면 스키마와 버전을 코드와 함께 관리하고, 다시 생성하기 전에 업스트림 변경 사항을 검토하세요. 이렇게 하면 엔드포인트나 응답 형식의 변경을 자동화가 조용히 중단된 뒤가 아니라 바로 확인할 수 있습니다.
FAQ
ZimaOS에서 영구 API 토큰을 생성할 수 있나요?
IceWhale의 당시 답변에 따르면 영구 토큰은 지원되지 않았으며, 현재 공개 문서에는 개인용 액세스 토큰 UI가 안내되어 있지 않습니다.
이전 액세스 토큰은 어떻게 얻었나요?
포럼 사용자는 /v1/users/login에 POST 요청을 보내 성공한 후 이를 얻었습니다.
API를 인터넷에 공개해야 하나요?
아니요. 신뢰할 수 있는 비공개 네트워크에서만 사용하고, 현재 지원되는 흐름을 통해 인증하세요.
Home Assistant 연동을 만들 수 있나요?
네, 하지만 토큰 만료, API 버전 변경, 최소 권한 액세스를 고려해 설계하세요.
