Mapping Application Users to Imou Sub-Accounts: Create, Look Up and Revoke

Map each eligible application user to an Imou sub-account created from that user’s mobile phone number or email address. createSubAccount returns an openid, which should become the stable Imou-side key in your backend mapping. Use getOpenIdByAccount to look it up, attach only required device policies, and remove permissions or delete the sub-account when access ends. This is account docking, not documented SSO or OIDC federation.

Why it matters

Your product user and an Imou sub-account are related identities, but they are not the same database record. Your identity provider owns login, passwords, sessions, multifactor authentication, tenant membership, and business roles. Imou account APIs provide a sub-account identifier and device authorization policy beneath the developer administrator account.

Keeping that boundary clear prevents two common errors:

• using the administrator accessToken as though it were an end-user session; and
• describing sub-account creation as identity federation that the API documentation does not claim.

The mapping architecture

Layer	Identifier	Responsibility
Your identity provider	user_id	Authentication and user lifecycle
Your SaaS/application	tenant_id, role, site assignment	Business authorization and ownership
Imou account docking	account, returned openid	Sub-account identity under the developer account
Imou policy	permission plus dev:/cam: resource	Device-operation authorization

A practical mapping table might contain:

Field	Purpose
user_id	Your immutable user key
tenant_id	Prevent cross-tenant joins
imou_account	The phone number or email supplied to the API
imou_openid	The sub-account ID returned or looked up
mapping_status	Pending, active, revoking, or deleted in your workflow
last_reconciled_at	Your audit and repair timestamp

These fields are an application design recommendation. The documented API facts are narrower: createSubAccount accepts an administrator accessToken and an account that is a mobile phone number or email, then returns openid.

Six-step lifecycle

1. Authenticate and authorize in your own system

Confirm the user belongs to the intended tenant and has a role that should receive camera access. Do not ask Imou sub-account APIs to replace your application login system.

2. Normalize the account value carefully

Choose the phone number or email address that will be used as account. Preserve a controlled canonical form in your backend so later lookups use the same business identifier. Consent, privacy, and retention handling remain your responsibility.

3. Create the sub-account

Call createSubAccount from a trusted backend:

{
  "params": {
    "token": "ADMIN_ACCESS_TOKEN",
    "account": "USER_EMAIL_OR_PHONE"
  }
}

The successful response contains:

{
  "result": {
    "data": {
      "openid": "SUBACCOUNT_OPENID"
    },
    "code": "0"
  }
}

The complete request also uses the normal signed Imou API envelope. Keep AppSecret and the administrator token off the client.

4. Persist the returned openid

Write the mapping transactionally in your application database. Treat openid as the Imou-side sub-account ID, not as an email, display name, or token. Avoid joining future permission jobs by mutable profile fields when you already have this stable key.

5. Assign and verify policy

Use addPolicy with openid, an authorization Policy, and the administrator accessToken. Give the user only the documented permissions needed on the intended dev: devices or cam: channels.

Use queryDevicePermission to inspect permissions for a device and optional channel, or listSubAccountDevice to page through devices assigned to the sub-account. listSubAccount can support account inventory.

6. Revoke on lifecycle events

When a user loses one site assignment, remove the corresponding device permission. When all authorization should end, clear the policy. When the sub-account relationship itself must end, use deleteSubAccount. Make revocation part of role changes and tenant offboarding, not a manual afterthought.

Recovering a missing mapping

If your database lacks openid but you still know the sub-account value, getOpenIdByAccount accepts:

• token: administrator accessToken
• account: the sub-account value

and returns openid.

{
  "params": {
    "token": "ADMIN_ACCESS_TOKEN",
    "account": "USER_EMAIL_OR_PHONE"
  }
}

Use this as a controlled recovery or reconciliation path. It does not remove the need to store a reliable mapping in your own system.

APIs in the lifecycle

Need	Official API	Key fact
Create identity mapping	createSubAccount	Phone or email in; openid out
Recover the Imou key	getOpenIdByAccount	Looks up openid from the sub-account value
Inventory sub-accounts	listSubAccount	Pages through developer-created sub-accounts
Grant resource access	addPolicy	Uses administrator token, openid, and Policy
Inspect effective scope	queryDevicePermission / listSubAccountDevice	Queries device/channel permissions
Remove one resource grant	deleteDevicePermission	Narrows access
Remove authorization policy	clearPolicy	Clears sub-account authorization
End the relationship	deleteSubAccount	Deletes the sub-account

What this is not

The account documentation does not describe createSubAccount as:

• an OIDC identity-provider connection;
• an SSO login redirect;
• exchange of your ID token for an Imou identity;
• SCIM provisioning; or
• automatic synchronization from your user directory.

Do not place those claims in architecture diagrams or sales copy. The documented flow is explicit API-driven sub-account creation, lookup, token retrieval, policy management, and deletion. If your product uses OIDC internally, that remains upstream of this mapping.

Limits and pitfalls

Reusing one sub-account for many product users

It weakens traceability and makes targeted revocation difficult. Prefer a one-to-one mapping for eligible users unless your reviewed design has a specific reason otherwise.

Storing only email or phone

Those values can change in your product. Persist the returned openid, while retaining the exact account value needed for audit or lookup according to your privacy policy.

Confusing openid with a credential

openid identifies the sub-account. It is not the administrator token, AppSecret, or proof that a current user session is valid.

Granting policy before tenant checks

Your backend must first verify tenant and role assignments. Platform policy should implement your approved scope, not decide your business ownership model.

Incomplete offboarding

Disabling a local login does not by itself document removal of Imou permissions. Trigger permission deletion, policy clearing, or sub-account deletion as appropriate, and reconcile the outcome.

Exposing administrator credentials

All account and policy operations should be made by the trusted backend. Never embed the administrator accessToken or AppSecret in browser JavaScript or a distributed mobile client.

A minimal reconciliation loop

Periodically compare three sets:

1. active application users and current tenant/site roles;
2. stored user_id to openid mappings; and
3. device/channel permissions returned by account APIs.

Repair missing mappings through approved create or lookup flows, remove stale grants, and flag ambiguous account changes for human review. This reconciliation pattern is architecture guidance, not an Imou service guarantee.

Register at Imou Open Platform to test the account-docking APIs, then keep your identity system, openid mapping, and device policies as three explicit layers.

Official sources

• createSubAccount
• getOpenIdByAccount
• Account docking interface list
• addPolicy
• listSubAccountDevice