Classify Imou HTTP Interfaces by Administrator vs Sub-Account Token

#camera #automation

Classify token authority per interface, not by the shared parameter name token. Current Imou pages require an administrator accessToken for control-plane work such as issuing sub-account tokens, changing policies, binding devices, configuring callbacks, and managing live addresses. Some device-facing queries accept administrator or sub-account tokens when the sub-account has the documented permission. The target interface page is always the final authority.

Why it matters

Using an administrator token for every request makes development look easy but collapses isolation. A user-facing defect or leaked credential can then reach account-wide controls. The reverse shortcut also fails: a sub-account token cannot be assumed to call administrative interfaces simply because they accept a field named token.

Imou account permissions are one layer. Your product must still authenticate the user, establish tenant and role membership, map the requested device or channel to that tenant, and decide whether the action is allowed. Only then should it select the narrowest platform credential accepted by the method.

Approach / architecture

Separate two backend paths:

Path	Typical caller	Credential	Responsibilities
Control plane	Restricted service or approved operator	Administrator `accessToken`	Sub-accounts, policies, binding, callbacks, service/live administration
User operation plane	Authenticated product workflow	Sub-account token where accepted	Permitted device/channel action

Keep both credentials server-side unless a documented client flow specifically requires otherwise. A sub-account token is still sensitive. Its reduced impact depends on correct policies and resource scope, not on its prefix or storage location.

Create a machine-readable interface register with: method, source URL, accepted token types, minimum sub-account permission, resource form, owner service, and last review date. Reject calls for which authority is unknown rather than falling back to administrator.

A documentation-bounded classification

Interface or family	Current documented token rule	Use
`accessToken`	Application credentials obtain administrator token	Bootstrap backend authority
`subAccountToken`	Administrator token plus `openid`	Issue a sub-account token
Account administration (`createSubAccount`, `deleteSubAccount`, `addPolicy`, `clearPolicy`)	Administrator control-plane flow; verify each page	Identity and permission lifecycle
`bindDevice`	Administrator token	Bind device to account
`setMessageCallback`	Administrator token	Configure callback subscription
`liveList`, `queryLiveStatus`	Administrator token on current pages	Inventory and inspect live addresses
`getAlarmMessage`	Administrator or sub-account token; current page documents minimum sub-account permission	User-scoped alarm query when authorized
`listDeviceDetailsByIds`	Administrator or sub-account token on current page	Device detail query within allowed scope

This is an implementation starting point, not a complete permanent matrix. Review every method you use. Similar-looking methods can have different authority requirements.

Seven implementation steps

Inventory actual calls. Extract every OpenAPI method used by backend routes, workers, scheduled jobs, and support tools. Do not classify a broad module while missing one write method.
Open each live method page. Record whether the parameter accepts administrator only or administrator/sub-account. Where documented, capture minimum permission and whether the resource is device- or channel-scoped.
Map product identities. Associate each application user or service role with the intended Imou sub-account openid where that model applies. Never share one user’s cached token with another.
Grant least privilege. Use only documented policy names and exact dev: or cam: resource forms applicable to the operation. Keep policy creation and removal in the administrator control plane.
Build an explicit credential selector. The caller supplies an operation identifier and authorized application identity; the selector looks up the reviewed rule. It must not choose administrator merely because a sub-account call failed.
Enforce product authorization first. Validate tenant, site, role, device/channel mapping, and action. A platform permission should be a second gate rather than the only gate.
Test denial and offboarding. Verify allowed calls, missing permission, wrong resource, deleted or cleared policy, user removal, and attempts to invoke administrator-only methods through a user route.

APIs / SDKs

The account docking summary lists sub-account creation, deletion, listing, token, policy, permission, and device-list interfaces. It is the canonical source for the account module’s scope.

Important method pages include:

accessToken, which obtains the administrator token using application credentials;
subAccountToken, which requires an administrator token and openid;
addPolicy, an administrator-authorized policy write;
bindDevice, which requires administrator authority;
setMessageCallback, which requires administrator authority;
queryLiveStatus, whose current page identifies administrator accessToken; and
listDeviceDetailsByIds, whose current page accepts administrator or sub-account token.

Method documentation can change. Store the source beside the rule and recheck it during release QA.

Credential-selection pattern

Avoid code such as “try sub-account; on authorization error retry as admin.” That converts a denied user operation into an elevated operation. Prefer a closed registry:

rule = reviewedInterfaceRegistry[method]
authorizeProductUser(user, resource, action)
credential = credentialStore.get(rule.requiredAuthority, user)
callOpenApi(method, credential, validatedParams)

This is architecture pseudocode, not an Imou SDK. Logs should contain method, request ID, region, rule version, and redacted resource—not the credential.

Limits & pitfalls

The parameter name token does not identify token authority.
Do not infer rules for an entire module from one method.
Do not use administrator authority as an automatic fallback after a denied sub-account call.
Do not assume every device query accepts a sub-account token; verify the specific page.
Do not invent permission names or resource syntax.
Do not treat a sub-account token as safe to log, embed, or reuse across identities.
Do not place AppSecret or administrator tokens in browsers, mobile apps, desktop logs, or public repositories.
Do not treat Imou policies as a replacement for SaaS tenant authorization.
Do not claim universal token lifetime, revocation timing, or propagation behavior without live documentation.
Recheck all write methods and minimum permissions before publication and production release.

Review the register whenever a new endpoint is introduced. Security review should ask not only “is the token valid?” but “why is this authority required, which product identity requested it, and what resource has already been authorized?”

Start with the live Imou account docking documentation, then build a reviewed per-interface authority register before connecting user workflows.

DEV Community