Aqara账号授权模式
Aqara账号授权模式主要用于使用Aqara Home APP添加设备,希望通过开放接口获取或控制您Aqara账号下的设备数据。Aqara账号授权模式支持两种授权方式:接口授权和OAuth2.0授权。
- Aqara账号:指通过Aqara Home APP,Aqara开发者平台等其他Aqara系统注册的手机号、邮箱账号,用户可以通过该账号登录到Aqara Home APP,绑定设备、控制设备或联动配置。
接口授权
第三方应用可通过API接口获取到用户相关授权许可,以允许第三方应用访问该用户相关信息(如设备列表、控制设备、联动配置等),而无需将用户名和密码提供给第三方应用。授权流程时序图如下所示。
![aqara-auth](https://cdn.aqara.com/cdn/luoshu/mainland/static/image/aqara-auth.png)
步骤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](https://cdn.aqara.com/cdn/luoshu/mainland/static/image/oauth2.0.png)
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
}