Aqara账号授权模式

Aqara账号授权模式主要用于使用Aqara Home APP添加设备,希望通过开放接口获取或控制您Aqara账号下的设备数据。Aqara账号授权模式支持两种授权方式:接口授权OAuth2.0授权

  • Aqara账号:指通过Aqara Home APP,Aqara开发者平台等其他Aqara系统注册的手机号、邮箱账号,用户可以通过该账号登录到Aqara Home APP,绑定设备、控制设备或联动配置。

接口授权

第三方应用可通过API接口获取到用户相关授权许可,以允许第三方应用访问该用户相关信息(如设备列表、控制设备、联动配置等),而无需将用户名和密码提供给第三方应用。授权流程时序图如下所示。

aqara-auth

步骤1 通过Aqara账号获取授权验证码authCode

  • 接口intent:config.auth.getAuthCode
  • 接口描述:本接口用于获取授权验证码Code,验证码有效期10分钟。
  • 请求参数:
名称 类型 是否必须 描述
account String Aqara账号信息(如:邮箱,手机号)
accountType int 账号类型,0-Aqara注册账号
accessTokenValidity String 访问令牌有效时长,单位天,默认7d。支持1~24h(小时),1~30d(天),1~10y(年) ,refreshToken时长默认为accessToken有期限+30天
  • 请求示例:
{
    "intent": "config.auth.getAuthCode",
    "data": {
        "account": "189000123456",
        "accountType": 0,
        "accessTokenValidity": "1h"
    }
}
  • 返回参数
名称 类型 描述
authCode String 验证码,通过手机短信或邮箱发送
  • 响应示例:
{
    "code": 0,
    "requestId": "",
    "message": "Success",
    "msgDetails": xxx,
    "result": {
        "authCode": ""
    }
}

步骤2 通过授权验证码authCode获取访问令牌accessToken

  • 接口intent:config.auth.getToken
  • 接口描述:在授权码Code过期前,通过此接口将授权码换取访问令牌accessToken,访问令牌的默认有效期为7天,可以通过步骤一自定义有效期时长。
  • 请求参数:
名称 类型 是否必须 描述
authCode String 上一步请求获取的authCode
account String Aqara账号信息(如:邮箱,手机号)
accountType Integer 账号类型,0-Aqara注册账号
  • 请求示例:
{
    "intent": "config.auth.getToken",
    "data": {
        "authCode": "xxxx",
        "account": "xxx",
        "accountType": 0
    }
}
  • 响应参数:
名称 类型 描述
expiresIn String accessToken过期时间,单位秒
openId String 用户唯一id
accessToken String 访问令牌
refreshToken String 访问刷新令牌,refreshToken时长默认为accessToken有期限+30天
  • 响应示例:
{
    "code": 0,
    "requestId": "",
    "message": "Success",
    "msgDetails": xxx,
    "result": {
        "expiresIn": "86400",
        "openId": "593652793976837702248177061889",
        "accessToken": "b8001e1893f5e4316a4f8c3b47df3720",
        "refreshToken": "ddd9dc7e9ec7b772e852121ed2fe75aa"
    }
}

步骤3 通过refreshToken刷新访问令牌,获取新的accessToken和refreshToken

  • 接口intent:config.auth.refreshToken
  • 接口描述:在accessToken过期前,通过此接口用refreshToken刷新访问令牌accessToken,refreshToken时长默认为accessToken有期限+30天。
  • 请求参数:
名称 类型 是否必须 描述
refreshToken String 访问刷新令牌
  • 请求示例:
{
    "intent": "config.auth.refreshToken",
    "data": {
        "refreshToken": "xxxx"
    }
}
  • 响应参数:
名称 类型 描述
expiresIn String accessToken过期时间,单位秒
openId String 用户唯一id
accessToken String 新的访问令牌
refreshToken String 新的访问刷新令牌
  • 响应示例:
{
    "code": 0,
    "requestId": "",
    "message": "Success",
    "msgDetails": null,
    "result": {
        "expiresIn": "86400",
        "openId": "593652793976837702248177061889",
        "accessToken": "b8001e1893f5e4316a4f8c3b47df3720",
        "refreshToken": "ddd9dc7e9ec7b772e852121ed2fe75aa"
    }
}

OAuth2.0授权

注意:仅Aqara账号可用于OAuth2.0授权模式。

OAuth2.0 是一个开放标准,允许用户让第三方应用访问该用户相关信息(如设备列表、控制设备、联动配置等),而无需将用户名和密码提供给第三方应用。此授权模式流程简单且安全,详细时序图如下所示。

oauth2

OAuth 2.0 详细授权流程如下:

步骤1 请求授权码

通过浏览器将用户重定向到OAuth 2.0服务,登录Aqara账号和密码后,可在返回链接中获取用户的授权码(code)。授权码的有效期为10分钟。

  • 请求URL:https://${domain}/v3.0/open/authorize,${domian}需替换对接服务地区的域名。
  • 请求方式:GET
  • 请求参数:
名称 类型 是否必须 描述
client_id String 第三方应用ID,对应系统的AppID
response_type String 返回类型,按照OAuth 2.0 标准,固定取值为code
redirect_uri String 第三方应用注册的重定向URI,即第三方自定义的跳转URL
state String 取值为任意字符串,认证服务器将原样返回该参数
theme String 页面主题,目前支持0、1两套主题,默认为主题0
  • 返回说明:
GET  HTTP/1.1 302 Found

Location: https://redirect_uri?code=xxx&state=xxx

步骤2 获取访问令牌

获得授权码后,访问以下URL,用授权码换取访问令牌(AccessToken)。

  • 请求URL:https://${domain}/v3.0/open/access_token,${domian}需替换对接服务地区的域名。
  • 请求方式:HTTP POST (application/x-www-form-urlencoded)
  • 请求参数:
名称 类型 是否必须 描述
client_id String 第三方应用ID,对应系统的AppID
client_secret String 第三方应用秘钥,对应系统的AppKey
redirect_uri String 第三方应用注册的重定向URI,即第三方自定义的跳转URL
grant_type String 根据OAuth 2.0 标准,固定取值为authorization_code
code String 上一步请求获得的授权码
  • 响应参数:
名称 类型 描述
expires_in String accessToken过期时间,单位秒
openId String 用户唯一id
access_token String 访问令牌
refresh_token String 访问刷新令牌
state String 原样返回该参数
  • 响应示例:
{
    "access_token": "2084aedc686a36f323c94ca76c631431",
    "refresh_token": "deb7f6079b7fa0cf47ead1268e5e7691",
    "openId": "710995681892841378791828500481",
    "state": "aiot",
    "expires_in": 86400
}

步骤3 刷新访问令牌

在access_token过期前使用refresh_token进行刷新,获取新的access_token,可设置定时循环刷新。

  • 请求URL:https://${domain}/v3.0/open/access_token,${domian}需替换对接服务地区的域名。
  • 请求方式:HTTP POST (application/x-www-form-urlencoded)
  • 请求参数:
名称 类型 是否必须 描述
client_id String 第三方应用ID,对应系统的AppID
client_secret String 第三方应用秘钥,对应系统的AppKey
redirect_uri String 第三方应用注册的重定向URI,即第三方自定义的跳转URL
grant_type String 根据OAuth 2.0 标准,固定取值为refresh_token
refresh_token String 上一步请求获得的刷新令牌
  • 响应参数:
名称 类型 描述
expires_in String accessToken过期时间,单位秒
openId String 用户唯一id
access_token String 新的访问令牌
refresh_token String 新的访问刷新令牌
  • 响应示例:
{
    "access_token": "2084aedc686a36f323c94ca76c631431",
    "refresh_token": "deb7f6079b7fa0cf47ead1268e5e7691",
    "openId": "710995681892841378791828500481",
    "expires_in": 86400
}
Copyright © 2023 深圳绿米联创科技有限公司 all right reserved,powered by Gitbook文档修改时间: 2024-09-27 21:51:47

results matching ""

    No results matching ""