Aqara Account Authorization Mode

Aqara account authorization mode mainly uses Aqara Home APP to add devices, and obtain or control device data under your Aqara account through open interfaces.

• Aqara account: refers to the phone number and email account registered through Aqara systems such as Aqara Home APP, Aqara Developer Platform, etc. Users can log in to Aqara Home APP through this account, bind devices, control devices or linkage configuration.

Interface Authorization

Third-party applications can obtain user-related authorization permissions through API interfaces to allow third-party applications to access user-related information (such as device lists, control devices, linkage configuration, etc.) without providing user names and passwords to third-party applications. The sequence diagram of the authorization process is shown below.

Step 1 Obtain the authorization verification code through Aqara account

• API intent: config.auth.getAuthCode
• Description: This interface is used to obtain the authorization verification code. The verification code is valid for 10 minutes.
• Request parameters

• Request Demo:

{
  "intent": "config.auth.getAuthCode",
  "data": {
    "account": "189000123456",
    "accountType": 0,
    "accessTokenValidity": "1h"
  }
}

• Response parameters

• Response demo:

{
  "code": 0,
  "requestId": "",
  "message": "Success",
  "msgDetails": null,
  "result": {
    "authCode": "xxxx"
  }
}

Step 2 Obtain the accessToken through the authorization verification code

• Obtain access-token

• API intent: config.auth.getToken

• Description: Before the authorization code expires, obtain the accessToken through the authorization code. The default validity period of the access token is 7 days, and the validity period can be customized through the "config.auth.getAuthCode" interface.
• Request parameters

• Request Demo:

{
  "intent": "config.auth.getToken",
  "data": {
    "authCode": "xxxx",
    "account": "xxx",
    "accountType": 0
  }
}

• Response parameters

• Response demo:

{
  "code": 0,
  "requestId": "",
  "message": "Success",
  "msgDetails": null,
  "result": {
    "expiresIn": "86400",
    "openId": "593652793976837702248177061889",
    "accessToken": "b8001e1893f5e4316a4f8c3b47df3720",
    "refreshToken": "ddd9dc7e9ec7b772e852121ed2fe75aa"
  }
}

Step 3 Refresh the accessToken through refreshToken to obtain new accessToken and refreshToken

• API intent: config.auth.refreshToken
• Description: Before the accessToken expires, refresh the access token with refreshToken through this interface. The refreshToken duration defaults to the period of accessToken + 30 days.
• Request parameters

• Request Demo

{
  "intent": "config.auth.refreshToken",
  "data": {
    "refreshToken": "xxxx"
  }
}

• Response parameters

• Response demo

{
  "code": 0,
  "requestId": "",
  "message": "Success",
  "msgDetails": null,
  "result": {
    "expiresIn": "86400",
    "openId": "593652793976837702248177061889",
    "accessToken": "b8001e1893f5e4316a4f8c3b47df3720",
    "refreshToken": "ddd9dc7e9ec7b772e852121ed2fe75aa"
  }
}

OAuth2.0 Authorization

Note: Only Aqara account can be used in OAuth2.0 authorization mode.

OAuth2.0 is an open standard that allows users to allow third-party applications to access user-related information (such as device lists, control devices, linkage configuration, etc.) without providing user names and passwords to third-party applications. This authorization mode process is simple and safe. The detailed sequence diagram is shown below.

The detailed authorization process of OAuth 2.0 is as follows:

Step 1 Request authorization code

Redirect the user to the OAuth 2.0 service through the browser. After logging in to the Aqara account and password, the user's authorization code (code) can be obtained in the return link. The authorization code is valid for 10 minutes.

• Request URL: https://${domain}/v3.0/open/authorize, ${domian} refers to the server domain name.
• Request Method: GET
• Request parameter

• Return demo

GET  HTTP/1.1 302 Found

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

Step 2 Obtain access token

After obtaining the authorization code, use the authorization code to request an access token (accessToken).

• Request URL: https://${domain}/v3.0/open/access_token, ${domian} refers to the server domain name.
• Request Method: HTTP POST (application/x-www-form-urlencoded)
• Request parameter

• Response parameter

• Response demo

{
    "access_token": "2084aedc686a36f323c94ca76c631431",
    "refresh_token": "deb7f6079b7fa0cf47ead1268e5e7691",
    "openId": "710995681892841378791828500481",
    "state": "aiot",
    "expires_in": 86400
}

Step 3 Refresh access token

Use refresh_token to refresh before the access_token expires, get a new access_token, and set a regular cycle refresh.

• Request URL: https://${domain}/v3.0/open/access_token, ${domian} refers to the server domain name.
• Request Method: HTTP POST (application/x-www-form-urlencoded)
• Request parameter

• Response parameters

• Response demo

{
    "access_token": "2084aedc686a36f323c94ca76c631431",
    "refresh_token": "deb7f6079b7fa0cf47ead1268e5e7691",
    "openId": "710995681892841378791828500481",
    "expires_in": 86400
}