First verify UTC time, nonce uniqueness, request id, App ID, App Secret, and regional endpoint against the current development specification. The client timestamp must remain within the documented five-minute platform window; the 32-bit nonce must not repeat within five minutes, or SN1005 is returned; and every request needs a unique, non-empty id. Then compare your signer with the official test vector.
Separate transport from authentication
Confirm HTTPS connectivity and the assigned SG, FK, or OR endpoint before changing signing code. A request can reach a server and still target the wrong account region. Keep the full response result code and request ID in a secure trace so the team can distinguish endpoint mismatch, stale credentials, replay protection, and signer defects.
Current request fields
The development specification defines system.ver, system.sign, system.appId, system.time, and system.nonce, plus params and top-level id. It describes time as a UTC timestamp in seconds, nonce as a 32-bit random value that cannot repeat within five minutes, and id as a unique non-empty string for every call.
Clock window and SN1005
The current page says the client time difference from the platform cannot be five minutes; operationally, keep the clock comfortably inside that five-minute boundary rather than aiming at the edge. It explicitly says reuse of the nonce within five minutes returns SN1005. Do not claim that all signature errors are SN1005 or invent a broader error-code mapping.
Use the official algorithm only
The live specification currently provides the signing-source order, password derivation, HMAC operation, Base64 output, Java sample, and a fixed standard test case. Implement those steps exactly from that page. This FAQ intentionally does not restate every byte-level detail because duplicated algorithms drift; the official page and its fixed expected value are the release gate.
Debugging sequence
- Confirm the assigned regional hostname. 2. Synchronize the server clock and emit UTC epoch seconds. 3. Generate a fresh nonce per request and prevent accidental reuse across workers. 4. Generate a fresh non-empty top-level
id. 5. Confirm App ID and App Secret belong together. 6. Run the official fixed test case locally. 7. Compare string encoding and final output only after the preceding checks pass.
Concurrency pitfalls
A copied request body, retry that reuses all system fields, shared pseudo-random seed, or cache keyed too broadly can repeat a nonce. Architecture recommendation: generate nonce and request ID at the final attempt boundary. If a business operation is retried, build a new authenticated envelope while preserving a separate internal correlation ID for observability.
Logging safely
Log UTC time, nonce hash or truncated value, request ID, App ID suffix, region, method, and result code. Never log App Secret, derived signing key, administrator access token, or full signed payloads in shared systems. A redacted canonical serialization can help compare environments without exposing credentials.
Common wrong turns
Do not change hash algorithms from memory, sort fields based on an unrelated API, use milliseconds where seconds are documented, reuse a captured nonce, send an empty request id, or assume local time formatting belongs in the numeric timestamp. Do not call credential rotation the first fix: it can hide the original configuration defect.
Soft CTA
Use the standard test case in the current development specification before testing a real credential. Register at Imou Open Platform and keep signer verification in backend CI so later refactors cannot silently change authentication output.
Verification discipline
Treat the linked live documentation as the boundary of the claim. Capture the page and review date in the release ticket, and recheck method names, fields, permissions, regions, and status values before publication. Console behavior and repositories can change after this draft. If the live source disagrees with this article, update the article rather than preserving an outdated assertion.
Secret handling
Keep App Secret values and administrator access tokens on a trusted backend. Do not place them in Home Assistant YAML shared publicly, browser bundles, mobile logs, screenshots, sample repositories, or support tickets. Redact device identifiers and live addresses in diagnostics. A live URL is operational data and should be distributed only through the authorization boundary designed by the application owner.
Capability and service boundaries
A documented platform method does not prove that every device, channel, account, or subscribed service supports the same outcome. Test with the actual account region and target device family. Present missing controls as a capability or service question first, then gather diagnostics, instead of promising universal behavior or inventing a model matrix.
Observability
Record the request ID, method, region, result code, and a redacted resource identifier for backend calls. Add timestamps around each stage so operators can distinguish local validation, platform rejection, device availability, and downstream delivery. Logs must never contain App Secret values, full administrator tokens, reusable live URLs, or unredacted callback payloads.
Rollout practice
Start with one test application, one account region, one device, and one channel. Validate the happy path and an intentional failure before expanding. A staged rollout makes region mistakes, quota pressure, unsupported capabilities, and stale credentials visible while the affected inventory is still small.
Architecture status
Unless a sentence is explicitly attributed to Imou or Home Assistant documentation, workflow choices in this article are recommendations, not platform guarantees. Queue design, caching, reconciliation, alert thresholds, and retry policy belong to the application operator. They should be tuned from measured behavior without being presented as an Imou SLA.
Official sources
Live-source review date: 2026-08-31. Recheck before publication.
Top comments (0)