ZimaOS has a documented OpenAPI now, but the old 2024 pattern of calling /v1/users/login and reusing the returned access token should be treated as a session-authentication technique, not a permanent API key system. IceWhale explicitly said permanent tokens were not supported in that thread.
Current OpenAPI documentation focuses on generated clients and service endpoints rather than a personal-access-token UI. For automation such as Home Assistant, keep authentication local, avoid exposing the login endpoint publicly, and design your integration to reauthenticate when a session token expires.
Use the Current OpenAPI Specifications
The current ZimaOS OpenAPI guide points developers to IceWhale's OpenAPI repository and shows generated clients for storage and other services.
The Historical Login Endpoint Returned an Access Token
In the source thread, the user successfully POSTed credentials to /v1/users/login and found an access token in the response. IceWhale then said permanent tokens were not supported.
Do Not Hardcode a Temporary Token Forever
A session token can expire or be invalidated by login/security changes. Store credentials or refreshed session state securely and handle authentication failures explicitly.
Keep the API on a Trusted Network
Do not port-forward internal ZimaOS API endpoints to the public internet. Use LAN, VPN, or ZimaClient/private networking to reach the server first.
Update Old ZimaOS Builds Before Developing Against Login APIs
ZimaOS had a critical authentication-bypass issue in versions through 1.5.0 affecting /v1/users/login; it was patched in 1.5.3. Always develop against a current stable release.
The ZimaOS login security advisory documents that security boundary.
Use Least Privilege in Home Assistant
If you are collecting temperature, CPU, power, or disk metrics, request only the data your integration needs. Avoid building automation that can also mutate users, storage, or system settings unless absolutely necessary.
Expect API Versions to Change
The current guide references versioned service paths such as /v2/local_storage. Do not assume every 2024 endpoint remains the preferred interface indefinitely; generate or update clients from current OpenAPI schemas.
The private access guide provides the safer network model.
Handle 401 Responses by Reauthenticating
A robust integration should treat an HTTP 401/expired-session response as a signal to obtain a fresh session rather than repeatedly retrying the same token. Add a bounded retry path so a login outage does not create an endless request loop.
Do Not Put Tokens in Logs
Home Assistant debug logs, shell history, screenshots, and Git repositories are common places for tokens to leak. Redact authorization headers and JSON login responses before sharing diagnostics publicly.
Pin the API Contract You Depend On
If your integration uses generated OpenAPI clients, keep the schema/version alongside your code and review upstream changes before regenerating. That makes it obvious when an endpoint or response shape changed instead of silently breaking automations.
FAQ
Can ZimaOS generate a permanent API token?
The source IceWhale reply said permanent tokens were not supported, and current public docs do not document a personal-access-token UI.
How was the old access token obtained?
The forum user obtained it after a successful POST to /v1/users/login.
Should I expose the API to the internet?
No. Keep it on trusted/private networking and authenticate through a current supported flow.
Can I build Home Assistant integration?
Yes, but design for token expiry, API version changes, and least-privilege access.
