POST /v2/authorizations/applyTokenAndInquiryUserInfo

With this API call, a merchant can obtain an access token and inquire about user information in the super app. The merchant is then authorized by users to provide services on the mini program. The specific information to query is defined by the scopes of the authorization code you obtained by calling the my.getAuthCode JSAPI.

Notes:

• When to make this API call:

• This API is recommended for the scenario where the merchant wants to query user information and shorten the response time. In this scenario, the scope of authCode should support the query of user information (for example, auth_user).
• For other scenarios, for example, the merchant doesn't want to query user information or have no strict requirement on the response time, we recommend the merchant call the applyToken API and the inquiryUseInfo API independently to get an accessToken or query user information.

• How to make this API call:

• Before calling this API, you must add the App_User_Authorization feature to your mini program in Mini Program Platform to access the API. For detailed instructions, refer to Add features.
• To get an access token for the first time, call the my.getAuthCode JSAPI to obtain an authorization code from the super app as the request parameter. Then call this API to exchange for an access token and inquire about user information in the super app.
• If the access token doesn't expire, call this API with the access token to query user information. In this scenario, this API can be used independently.
• When the original access token expires, use the refresh token to exchange for a new access token and inquire about user information directly. In this scenario, this API can be used independently.

• How to keep accessToken:

• An access token should be kept in the merchant server only, which means it should not be returned to the mini program.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

• Request header
• Response header

Request parameters

{
    "memo": "memo"
}

Response parameters

{
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
}

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Error codes

Error codes are usually classified into the following categories:

• Common error codes are common for all mini program OpenAPIs in V2.  
• API-specific error codes are listed in the following table.

Samples

Obtain access token and query user information

The data flow to obtain an access token and inquire about a user's information is illustrated as follows:

1. The mini program calls the my.getAuthCode JSAPI to request an authorization code from the super app.
2. The super app processes the request and shows the information that needs to be authorized.
3. The user confirms the authorization in the super app.
4. The super app service processes the authorization information to the super app server.
5. The super app server verifies the authorization information and then generates the authorization code.
6. The super app server returns the authorization code to the super app service.
7. The super app service returns the authorization code to the mini program.
8. The mini program sends the authorization code to the merchant server.
9. The merchant server calls this API to exchange for an access token from the super app server and inquire about user information.
10. The super app server verifies the authorization code and generates the access token.
11. The super app server inquires about user information by the access token.
12. The super app returns the access token and user information to the merchant server.

Request

• Use an authorization code to exchange for an access token and inquire about the user's specific information

{
  "appId":"3333010071465913xxx",
  "authClientId": "202016726873874774774xxxx",
  "userInquiryType": "AUTHORIZATION_CODE",
  "customerBelongsTo": "CHOPE",
  "authCode": "2810111301lGZcM9CjlF91WH00039190xxxx"
}

• The user of CHOPE authorizes the merchant.
• The mini program (3333010071465913xxx) calls the my.getAuthCode JSAPI to obtain the authorization code (2810111301lGZcM9CjlF91WH00039190xxxx) and then send the authorization code to the merchant (202016726873874774774xxxx). The merchant uses the authorization code to exchange for an access token and inquire about the user's specific information as the value of userInquiryType is AUTHORIZATION_CODE.

• Use a refresh token to exchange for an access token and inquire about the user's specific information

{
  "appId":"3333010071465913xxx",
  "authClientId": "202016726873874774774xxxx",
  "userInquiryType": "REFRESH_TOKEN",
  "customerBelongsTo": "CHOPE",
  "refreshToken": "2810111301lGZcM9CjlF91WH00039190xxxx"
}

The value of userInquiryType is REFRESH_TOKEN, which means the merchant can obtain an access token and inquire about the user's specific information by the refresh token (2810111301lGZcM9CjlF91WH00039190xxxx).

Response

{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
    "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
    "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811xxxx",
    "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
  "userInfo": {
    "userId": "1000001119398804xxxx",
    "status": "ACTIVE",
    "nickName": "Jack",
    "userName": {
      "fullName": "Jack Sparrow",
      "firstName": "Jack",
      "lastName": "Sparrow"
    },
    "avatar": "http://example.com/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx",
    "gender": "MALE",
    "birthDate": "2020-07-25",
    "nationality": "US", 
    "loginIdInfos": [
      {
        "loginId": "1116874199xxx",
        "loginIdType": "MOBILE_PHONE"
      }
     ],
    "contactInfos": [
      {
        "contactNo": "1116874199xxx",
        "contactType": "MOBILE_PHONE"
      }
    ],
    "extendInfo": "{\"appUserId\":\"200xxxx\",\"acqUserId\":\"300xxxx\"}"
  },
    "extendInfo": ""
}

• result.resultStatus is S, which shows the request to obtain an access token and inquire about the user's specific information is successful.
• The authorized merchant can use the access token (281010033AB2F588D14B43238637264FCA5AAF35) before accessTokenExpiryTime (2019-06-06T12:12:12+08:00).
• 1000001119398804xxxx is the user who authorizes the merchant.
• The authorized merchant can use the refresh token (2810100334F62CBC577F468AAC87CFC6C9107811) to exchange for a new access token and inquire about the user's specific information before refreshTokenExpiryTime (2019-06-08T12:12:12+08:0).
• userInfo describes the user's information you get via the applyTokenAndinquiryUserInfo API. The information includes userId, status, nickName, userName, avatar, gender, birthDate, nationality, loginIdInfos, contactInfos, and extendInfo.

Query user information by access token

The data flow of inquiring about a user's information is illustrated as follows:

1. The merchant server calls this API with the access token to inquire about the user's information.
2. The super app server returns the user's information to the merchant server based on the scopes of the access token.

Request

{
  "appId": "3333010071465913xxx",
  "authClientId": "202016726873874774774xxxx",
  "userInquiryType": "ACCESS_TOKEN",
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
  "customerBelongsTo": "CHOPE"
}

The merchant (202016726873874774774xxxx) uses the access token (281010033AB2F588D14B43238637264FCA5AAF35xxxx) to access the user's specific information.

Response

{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
  "userInfo": {
    "userId": "1000001119398804xxxx",
    "status": "ACTIVE",
    "nickName": "Jack",
    "userName": {
      "fullName": "Jack Sparrow",
      "firstName": "Jack",
      "lastName": "Sparrow"
    },
    "avatar": "http://example.com/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx",
    "gender": "MALE",
    "birthDate": "2020-07-25",
    "nationality": "US", 
    "loginIdInfos": [
      {
        "loginId": "1116874199xxx",
        "loginIdType": "MOBILE_PHONE"
      }
     ],
    "contactInfos": [
      {
        "contactNo": "1116874199xxx",
        "contactType": "MOBILE_PHONE"
      }
    ],
    "extendInfo": "{\"appUserId\":\"200xxxx\",\"acqUserId\":\"300xxxx\"}"
  }
}

• result.resultStatus is S, which means the inquiry request is successful.
• userInfo describes the user's information you get via the applyTokenAndInquiryUserInfo API. The information is based on the scopes of the access token, including userId, status, nickName, userName, avatar, gender, birthDate, nationality, loginIdInfos, contactInfos, and extendInfo.

Related links

my.getAuthCode

my.getAppIdSync

/v2/authorizations/applyToken

/v2/users/inquiryUserInfo