LifeSmart Cloud Authentication#

The LifeSmart integration authenticates against LifeSmart's cloud API using a two-step login flow (/auth.login → /auth.do_auth), then issues all subsequent requests with a signed usertoken. The implementation lives across three files:

• config_flow.py — HA config-flow steps, credential collection, error surfacing
• core/openapi_client.py — HTTP calls, signing, region-URL generation
• diagnostics.py — error-code → advice mapping

Two-Step Login Flow#

Password-based login is triggered when the user selects the password auth method in Step 1 of the cloud flow 1. The full flow is implemented in login_async():

Step 1 — /auth.login (unsigned POST)

Sends uid, pwd, and appkey to the base API URL. On success the server returns a short-lived token, a userid, and critically a rgn field that identifies the user's home region 2.

Step 2 — /auth.do_auth (unsigned POST)

Uses the token and userid from Step 1, plus appkey and rgn (falling back to the user's configured region if the server omitted it), to exchange for a long-lived usertoken 3. After this call, the client updates its internal _usertoken, _region, and _userid in place.

Token-based auth (the other method) skips both steps entirely — the user provides a pre-obtained usertoken directly, and the config flow proceeds straight to device enumeration 4.

After a successful login, the usertoken and authoritative region are written back into config_data so they persist in the HA config entry 5.

Token refresh is available via async_refresh_token() which calls /auth.refreshtoken with a flat signed body (different signing scheme from regular API calls).

Region Propagation#

The integration supports eight region codes 6:

The region is used in two URL-building methods in LifeSmartOAPIClient:

• REST API base URL — _get_api_url(): https://api.{region}.ilifesmart.com/app (falls back to https://api.ilifesmart.com/app when region is unset or AUTO).
• WebSocket URL — get_wss_url(): wss://api.{region}.ilifesmart.com:8443/wsapp/.

Critical: The /auth.login response may return a different rgn than the one the user originally selected. login_async() propagates it to self._region 7, and validate_input() propagates it into config_data so subsequent REST and WebSocket calls use the correct region 8. Without this propagation, cn0/cn1/cn2 users would end up hitting the wrong regional endpoint.

Request Signing#

Every regular API call (not login/do_auth) goes through _async_call_api(). The signature is an MD5 hash of a comma-separated string built from: method, any sorted params, time (Unix timestamp), userid, usertoken, appkey, and apptoken 9. The hash is placed in the system.sign field of the JSON body.

Auth error codes 10004, 10005, and 10006 are treated specially — they raise LifeSmartAuthError instead of the generic LifeSmartAPIError, causing HA to trigger a re-auth flow 10.

Error Code Mapping#

diagnostics.py maps LifeSmart numeric error codes to a (description, advice, category) tuple via get_error_advice() 11. The config flow calls this whenever LifeSmartAuthError.code is set, using the advice string as the errors["base"] key shown to the user 12.

Key auth-related codes 13:

Unknown codes within ranges 10000–10100, 10100–10200, and 20000–20100 are categorized generically rather than causing a crash 14.