OAuth 2.0 授权
OAuth 2.0 授权
Imou 开放平台的 OAuth 2.0 授权，让第三方应用在终端用户确认后，代其访问该用户 Imou Life 账号下的设备。用户在平台授权页登录并同意后，应用可查询与配置设备、接收消息、调用物模型、获取直播流等能力。
1. 产品概述
OAuth 2.0 是一种委托授权机制：设备归属终端用户，第三方应用仅在用户同意后才能访问。用户在 Imou Life 授权页登录并确认后，应用获得可过期、可刷新的 access token。
一次授权涉及四方：
| 角色 | 在本产品中的含义 |
|---|---|
| 终端用户 | 拥有设备的 Imou Life 账号 |
| 第三方应用 | 开发者在平台创建的 OAuth 项目；Project Access Key 与 Project Secret Key 为项目凭证 |
| 授权服务 | 开放平台提供的授权 H5 页，以及换发 token 的接口 |
| 设备服务 | 设备、视频、消息、物模型等 Open API |
开发者先在控制台创建 OAuth 项目，取得授权页 URL 与项目密钥。终端用户打开授权页，将其账号下设备授权给该项目。平台将授权码推送到开发者配置的回调 URL。开发者用项目密钥与授权码换取 access token，再调用 OAuth 相关 API 操作已授权设备。
授权有效期：90 天
每位终端用户的授权有效期为 90 天。到期后须重新授权，应用才能继续操作该用户设备。用户可在到期前再次授权以刷新有效期。
授权成功后，可使用的能力包括：
- 设备信息、在线状态、能力集、改名、升级及升级进度
- 设备配置
- 设备消息
- IoT 物模型
- 按设备、通道、主/子码流获取 RTSP 直播地址
接口说明见 OAuth 授权 API。调用时使用 OAuth 项目的 Access Key / Secret Key，并携带终端用户的 access token（Ot_ 前缀）。该路径与 子账号与授权策略 并行，不得与管理员或子账号 token 混用。
2. 适用场景
适用于在用户确认授权后，对接终端用户自有 Imou 设备的应用，例如：
- 物业、社区、养老、保险、零售等平台，将住户或客户的摄像机纳入自有 App 或管理后台。
- 智能家居、安防平台需要直播、告警消息或物模型，且仅在用户在授权页确认后开通。
- 具备服务端的应用：Project Secret Key 仅保存在服务端，由服务端接收授权码、换 token 与刷新 token。
每个 OAuth 项目对应一个第三方应用；授权页展示项目名称与 Logo，便于用户识别授权对象。
3. 计费
按已授权的终端用户数计费。每位授权用户每月包含下列免费额度：
| 项目 | 每月免费额度 |
|---|---|
| API 调用 | 1,000 次 |
| 消息推送 | 2,000 条 |
| 媒体流量（Media Flow） | 0.5 GB |
超出部分按资源单价从开发者预付费账户扣减。API 调用、消息推送与媒体流量的标准价见官网价格页：https://open.imoulife.com/price。
3.1 OAuth 用户流量额度（可选）
除平台默认的按用户免费 Media Flow 外，可为每位已授权终端用户单独配置自然月流量上限（GB）：调用 saveOauthUserQuota 设置、quotaGb 留空表示不限制；调用 queryOauthUserQuota 查询当月可用额度。请求须携带该用户的 OAuth access token（Ot_ 前缀）。概念说明见 资源池额度管理 · OAuth 终端用户流量额度；与子账号/设备通道资源池不是同一套模型。
4. 授权流程
登录 open.imoulife.com，按下列顺序完成对接。
4.1 创建 OAuth 项目并提交审核
使用开发者账号登录控制台，进入 OAuth 菜单，填写第三方应用信息：
- OAuth 项目 Logo 与名称（均展示在授权 H5 页）。
- 授权成功通知 URL：用户完成授权后，平台向该地址推送授权码。
提交项目并等待审核。
4.2 获取授权页与项目密钥
项目创建后，在控制台获取：
| 控制台项 | 用途 |
|---|---|
| User Authorization H5 Page | 授权页 URL，嵌入第三方应用供终端用户打开、登录并授权 |
| Project Access Key、Project Secret Key | OAuth 项目 AK/SK，用户授权后用于调用 API |
| Callback Url after authorization | 授权成功通知 URL，用于接收授权码 |
Project Secret Key 仅保存在开发者服务端。
4.3 终端用户授权
第三方应用打开 User Authorization H5 Page。终端用户登录 Imou Life 账号并确认后，其账号下设备即授权给该 OAuth 项目。
下图为授权页示例：展示 OAuth 项目名称，用户登录并确认授权。
4.4 接收授权码并换取 token
授权完成后，平台向 Callback Url 推送授权码，体现在回调 URL 的 code 参数中。
服务端使用项目 AK/SK 与授权码调用 oauthTokenV2：
- 请求 URL：
POST /openapi/oauthTokenV2 - 鉴权：
Authorization头为 Basic，值为AK:SK的 Base64 编码 - 换 token：
grant_type=authorization_code，提交授权码，并将redirect_uri设为与 OAuth 项目控制台一致的回调 URL
成功响应字段：
| 字段 | 说明 |
|---|---|
| access_token | 终端用户 access token，类型为 bearer |
| expires_in | 有效期 7200 秒 |
| refresh_token | access token 过期后用于刷新 |
| scope | 授权范围，当前为 all |
4.5 操作已授权设备
取得 access token 后，使用同一项目 AK/SK 调用设备、消息、物模型与拉流等 API。RTSP 地址见 getStreamUrl。Project Access Key 标识 OAuth 项目，access token 标识终端用户。按设备序列号、通道与码流类型返回 RTSP 播放地址：主码流为 0，子码流为 1。
access token 将过期时，通过 oauthTokenV2 刷新：grant_type=refresh_token，提交 refresh_token。成功则返回新 access token，无需用户再次打开授权页。
授权用户的资料变更、删除/修改/停用授权等，不在上述入门流程内，请以当前控制台与 API 文档为准。