Your First Signed Imou OpenAPI Request: AppId, accessToken and a Trusted Backend

Make the first OpenAPI call from a trusted backend, not from a browser or mobile binary. Create an application in the Imou Open Platform console, store appId and appSecret in a secret manager, send HTTPS POST requests to the data center assigned to that application, sign every envelope exactly as the current development specification describes, then obtain an administrator accessToken before calling device or account methods. Recheck the live signing page on the day you ship.

Why it matters

A first request that “works from a laptop script” can still be unsafe. If appSecret is compiled into an app, pasted into a frontend, or logged with the signature source string, later token and device work inherits that leak. A first request that hits the wrong regional host can also look like a signing bug. Treat the first call as a control-plane bootstrap: identity, region, clock, nonce, request id, and secret placement.

This article is a code-path onboarding note. It is not a product roadmap and does not replace per-method pages.

Approach / architecture

Keep a narrow bootstrap path:

Step	Owner	Must stay off clients
Application credentials	Secret manager / backend config	appSecret
Regional host	Reviewed config from console assignment	User-supplied base URL
Signed envelope	Backend signer module	Signing key and raw secret material
Administrator accessToken	Backend token cache	Browser, mobile, desktop logs
Device or account method	Backend after product authorization	Administrator token on user devices

console appId + appSecret
  -> backend signer (system.time, system.nonce, system.sign, id)
  -> HTTPS POST https://<assigned-host>/openapi/<method>
  -> accessToken (administrator)
  -> later device / account / callback methods

The signer and the HTTP client should be separate modules so you can tell a host mismatch from a signature defect. This split is architecture guidance, not an Imou SDK.

Seven implementation steps

1. Create the developer application and record the assigned data center. Use the international console. Note appId and the data center shown under Control Board → Basic Information → My Information. Do not pick a host from user geography.

2. Store credentials only on the backend. Load appId and appSecret from a secret manager. Never commit them, never embed them in OpenSDK sample apps you ship, and never return them to a browser.

3. Select the documented regional URL. Current development specification maps East Asia to openapi-sg.easy4ip.com, Central Europe to openapi-fk.easy4ip.com, and Western America to openapi-or.easy4ip.com, with HTTPS POST under /openapi/[method]. Recheck that table before production.

4. Implement the live signing procedure, then prove it with the official test vector. Copy algorithm order, encoding, and HMAC details only from the development specification. Run the page’s fixed test case locally. Do not put the example secret into production.

5. Emit a unique envelope per attempt. Use UTC seconds for system.time inside the documented five-minute window. Generate a 32-bit nonce that does not repeat within five minutes. Give every request a unique non-empty top-level id. Reusing a nonce in that window currently returns SN1005.

6. Call accessToken from the backend. Use application credentials as the current accessToken page requires. Cache the token according to that page’s lifetime rules; do not invent a longer cache. Log request id and result code, not the secret or the full token.

7. Only then call a read-only device or account method. Confirm the method’s token requirement on its own page. A successful accessToken call does not prove binding, events, storage, or live addresses.

APIs / SDKs

• HTTP development specification: hosts, envelope, signature, time, nonce, id, SN1005.
• accessToken: administrator token using application credentials.
• Account docking summary: which later methods need administrator versus sub-account tokens.

Do not invent SDK method names for HTTP signing. Client OpenSDK does not replace this backend bootstrap.

A first-request failure workbook

When the first call fails, change one variable at a time:

1. Confirm the international developer account and appId pair with the secret you loaded.
2. Confirm the console-assigned data center matches the host in config.
3. Confirm the path is /openapi/ plus the documented method name.
4. Confirm UTC seconds, not milliseconds, for system.time.
5. Confirm nonce uniqueness across processes; a shared counter or copied request body is a common SN1005 cause.
6. Confirm id is present, unique, and not an empty string.
7. Compare your signer output with the official fixed test case before blaming the network.

Keep a redacted trace: environment, region enum, method, UTC time, nonce fingerprint, request id, HTTP status, and platform result code. Never include appSecret, derived keys, or administrator tokens in that trace.

If two environments disagree, compare region and credential pairing first. Teams often copy a signer that is correct and a host that belongs to another application.

What “done” means for bootstrap

The first signed request is complete only when all of the following are true:

• secrets are loaded from a backend secret store;
• the official signature test vector passes in CI or a controlled local harness;
• accessToken succeeds against the assigned regional host;
• logs can explain a failure without revealing credentials;
• the next method to call has a reviewed token and permission rule.

Anything less is a prototype, not a production bootstrap. Expanding from here into binding, callbacks, or live addresses without this baseline usually multiplies the same secret and region mistakes.

Limits & pitfalls

• Do not sign requests in a browser, mobile app, or untrusted worker that can dump memory.
• Do not treat a 200 HTTP status as a successful business result; read the platform result code.
• Do not retry a failed call by replaying the same time, nonce, and id.
• Do not mix international hosts with a China-region portal.
• Do not infer data residency, SLA, or failover from sg / fk / or.
• Do not skip the official test vector and debug production secrets instead.
• Recheck the live specification on publication day.

Open the live development specification from Imou Open Platform, prove the official signature test case on a backend, then request accessToken for that same assigned region.