With this solution, merchants can learn how to obtain users' authorization to access user information on their mini programs. For more information about mini programs, see About Mini Programs.

User authorization is based on the industry-standard OAuth2.0 authorization mechanism. When users open and use a mini program, the mini program needs to get the users' consent so that the users allow the mini program to obtain basic user information, such as avatar, nickname, gender, etc., which is stored in the super app.

Note: This solution is aimed at mini programs that are released to AlipayCN (Alipay China). If you release your mini program to Alipay+ partner apps, refer to the Alipay+ user authorization solution.

How it works

The following diagram illustrates the workflow for mini programs to obtain user authorization:

The steps in the diagram are described as follows:

Step 1-2: A user logs in to a super app (Alipay China) and accesses a mini program on the super app. The mini program sends an authorization request to the super app.

Step 3-5: The super app displays an authorization page to the user and the user confirms to grant the authorization. Then the super app returns the authorization code to the mini program.

Step 6-9: The mini program sends a request to obtain an access token using the authorization code. AIMPDP (Alipay International Mini Program Development Platform) forwards the request to the super app and the super app returns an access token. AIMPDP sends an access token to the mini program.

To learn how mini programs are developed and launched, see Platform Guide.

The following documents will explain more about the authorization from a developer's point of view.

Basic concepts

Check the basic concepts below to understand more about user authorization:

Guidelines

When obtaining user authorization, stick to the following guidelines:

• Do not intentionally guide users to grant authorization when users open the mini program. Users have the right to fully understand the mini program and its operations before giving any decision.
• Fully respect the privacy of users and handle user authorization properly. If a mini program is found to handle user authorization unreasonably or beyond the agreed scope, AIMPDP has the right to permanently withdraw this authority of the mini program.

How to obtain user authorization

To obtain user authorization, follow the steps below:

Before you start

Make sure you have completed all the following steps:

1. Apply for an account.
2. Log in to the Alipay Global Merchant portal and click Manage to navigate to AIMPDP to manage mini programs.
3. Create a mini program.
4. Configure your merchant public key and obtain the platform public key. These two public keys are required when calling an openAPI. For detailed steps, see Configure signature keys.

Note: For more information about openAPI signature, see OpenAPIs Overview and Call an API via adding a signature.

5. Add the user authorization feature. For detailed steps, see Add features.
6. Follow the guidelines to authorize AIMPDP to call AlipayCN's APIs on behalf of the merchant. This step is required in user authorization because the merchant needs to call the OpenAPIs in the user authorization feature provided by AIMPDP, and AIMPDP will forward the requests to AlipayCN.
7. Contact your solution architect for permission to call the my.getSiteInfo and my.getAuthCode JSAPIs.

Procedures

Step 1: Obtain authCode from the super app

The sequence diagram below illustrates how a merchant's mini program obtains authCode from the super app:

The detailed steps are as follows:

1. A user opens a merchant's mini program. The mini program invokes my.getAuthCode(scopes) to send an authorization request to the super app and will fetch authCode in the success callback. (Step 1.1)

Note: We recommend you call my.getAuthCode(scopes) with auth_user.

2. The super app processes the request and displays an authorization page to the user. (Step 1.1.1)
3. After the user confirms the authorization, choose one of the following to get authCode:

• The merchant server invokes the applyToken API with authCode and the API call returns only userId. When invoking the inquiryUserInfo API, the API call will return specific user information.
• The merchant server invokes the applyTokenAndInquiryUserInfo API to get an access token and obtain user information with one API call.

4. Then the mini program calls the my.getAppIdSync JSAPI and gets appId from the super app. (Step 2.1.2)
5. The mini program calls the my.getSiteInfo JSAPI and gets customerBelongsTo from the super app.
   (Step 2.1.4)

Note:

• We recommend you not to call my.getAuthCode(scopes) with auth_base. auth_base indicates silent authorization, which means the super app will not display an authorization page to the user. The merchant server invokes the applyToken API with authCode and the API call returns only userId. When invoking the inquiryUserInfo API, the API call will get a response error with INVALID_ACCESS_TOKEN.
• The authCode, appId, and customerBelongsTo are required to get accessToken in Step 2.

Step 2: Obtain accessToken

With the obtained authCode, appId, and customerBelongsTo, you can exchange accessToken and userId.

The following sequence diagram illustrates how to obtain accessToken from AIMPDP:

The steps in the diagram are described as follows:

1. The merchant's mini program obtains the accessToken from the merchant server. During this process, authCode, appId, and customerBelongsTo are required [1].
2. The merchant server initiates a request to obtain the access token via the applyToken API [1.1]. Before calling the applyToken API, signing the request is needed. To learn more, see Call an API via adding a signature.
3. Then the merchant server sends the request via /v2/authorizations/applyToken to AIMPDP. During this process, authCode, appId, and customerBelongsTo are required [1.2].
4. AIMPDP processes the request and returns accessToken [1.3].
5. The merchant server validates the signature, creates a login session, and then saves accessToken [1.6].
6. The merchant server returns the request result to the mini program [1.7].

Note:

• For more about the applyToken API, refer to /v2/authorizations/applyToken.
• During this process, the clientId, public key, and private key are required. To learn more, see Before you start.

With the above steps, you have now completed the configuration of user authorization. The following sections introduce the extended steps to query user information.

Step 3: (Optional) Query user information

You can decide which kind of information you want to inquire about tailored to your business. User information includes nickName, avatar, gender, etc.

The following sequence diagram illustrates how to query user information via accessToken:

The steps in the diagram are described as follows:

1. The merchant's mini program sends a request to query user information with appId [1].
2. The merchant server processes the request and gets the user's accessToken [1.1].
3. The merchant server initiates a request to inquire user information via the inquiryUserInfo API [1.2]. Before calling the inquiryUserInfo API, signing the request is needed. To learn more, see Call an API via adding a signature.
4. Then the merchant server sends the request via /v2/users/inquiryUserInfo to AIMPDP [1.3]. AIMPDP processes the request and returns the user information [1.4].
5. The merchant server validates the signature and gets the user information [1.6].
6. Then the merchant server sends the request result to the merchant's mini program [1.7].

For more about the inquiryUserInfo API, refer to /v2/users/inquiryUserInfo.

API list

Refer to the following two tables for the APIs that are used in the above procedures:

JSAPI

OpenAPI

More information

Alipay+ user authorization solution

Alipay+ merchant onboarding

Alipay technical support

Manage Alipay+ mini programs in Alipay China