OAuth 2.0 authorization

OAuth 2.0 Authorization on the Imou Life Open Platform gives third-party applications delegated access to an end user's Imou Life devices. After the end user signs in and confirms on the platform authorization page, the application can access the devices under that account to query devices, configure devices, receive messages, call thing models, and obtain live video streams.

1. Product overview

OAuth 2.0 Authorization is a delegated authorization mechanism. The devices belong to the end user. A third-party application accesses those devices only with the user's consent. The user signs in and confirms on the Imou Life authorization page, and the application receives an access token that expires and can be renewed.

One authorization involves four parties:

The developer first creates an OAuth project on the Open Platform and obtains the authorization page URL and the project keys. The end user opens the authorization page and grants the devices under their account to that project. The platform delivers the authorization code to the callback URL configured by the developer. The developer uses the project keys and the authorization code to exchange an access token, then calls OAuth APIs to operate the authorized devices.

Authorization validity: 90 days

An end user's authorization is valid for 90 days. After it expires, the end user must authorize again before the application can continue to operate that user's devices. The user can authorize again before the current period expires. Doing so refreshes the authorization validity period.

After authorization, the following capabilities are available:

• Device information, online status, capability set, rename, upgrade, and upgrade progress
• Device configuration
• Device messages
• IoT thing model
• RTSP live stream URL by device, channel, and main or sub stream

API reference: OAuth authorization APIs. Calls use the OAuth project's Access Key and Secret Key, and carry the end user's access token (Ot_ prefix). This path is separate from sub-accounts and policies; do not mix OAuth user tokens with administrator or sub-account tokens.

2. Applicable scenarios

This applies to applications that connect to an end user's own Imou devices, with the authorization confirmed by the user:

• Property, community, care, insurance, and retail platforms that bring residents' or customers' cameras into their own app or admin console.
• Smart home and security platforms that need live video, alarm messages, or thing models, and enable them only after the user confirms on the authorization page.
• Applications that have a server. The project Secret Key stays on the server. The server receives the authorization code, exchanges it for tokens, and refreshes those tokens.

Each OAuth project corresponds to one third-party application. The authorization page shows that project's name and logo, so the user can tell what they are authorizing.

3. Billing

Fees are charged per authorized end user. Each authorized user includes the following free quota every month:

Usage beyond the free quota is deducted from the developer's prepaid account balance at the resource unit price. Standard prices for API calls, message pushes, and Media Flow are those published on the official price page: https://open.imoulife.com/price.

3.1 OAuth user flow quota (optional)

In addition to the default free Media Flow per authorized user, you can set a calendar-month cap in GB for each end user: saveOauthUserQuota to configure (empty quotaGb means no cap), queryOauthUserQuota to read the current value. Calls must use that user's OAuth access token (Ot_ prefix). See Resource pool quota · OAuth end-user flow quota. This is not the same model as sub-account or device-channel resource pools.

4. Authorization flow

Sign in at open.imoulife.com and complete the integration in the following order.

4.1 Create an OAuth project and submit it for review

Sign in to the console with a developer account, open the OAuth menu, and fill in the third-party application information:

• The logo and name of the OAuth project. Both are shown on the authorization H5 page.
• The authorization success notification URL. After the user completes authorization, the platform pushes the authorization code to this URL.

Submit the project and wait for review.

4.2 Obtain the authorization page and project keys

After the project is created, obtain the following from the console:

Keep the Project Secret Key on the developer's server.

4.3 End-user authorization

The third-party app opens the User Authorization H5 Page. After the end user signs in to their Imou Life account and confirms, the devices under that account are authorized to this OAuth project.

The figure below is an example of the authorization page. The page shows the OAuth project name. The user signs in with an Imou Life account and confirms the authorization.

4.4 Receive the authorization code and exchange it for tokens

After authorization, the platform pushes the authorization code to the Callback Url. The code appears in the code parameter of the callback URL.

The developer's server uses the project AK/SK and the authorization code to call oauthTokenV2.

• Request URL: POST /openapi/oauthTokenV2
• Authentication: the Authorization header uses Basic authentication. The value is the Base64 encoding of the project Access Key and Secret Key joined as AK:SK
• Exchange the code for tokens: set grant_type=authorization_code, submit the authorization code, and set redirect_uri to the same callback URL configured for the OAuth project

A successful exchange returns:

4.5 Operate authorized devices

With the access token, use the same project AK/SK to call the device, message, thing model, and stream APIs. For RTSP playback, see getStreamUrl. The project Access Key identifies the OAuth project, and the access token identifies the end user. The API returns an RTSP playback URL by device serial number, channel, and stream type. The main stream value is 0. The sub stream value is 1.

Before the access token expires, renew it with oauthTokenV2. Set grant_type=refresh_token and submit refresh_token. A successful renewal returns a new access token. The end user does not need to open the authorization page again.

Changes to an authorized user's profile, and deleting, modifying, or disabling an authorization, are outside the onboarding flow above. Handle them according to the current Open Platform console and API documentation.