With this solution, merchants can learn how to obtain users' authorization to access user information on 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 Alipay+ partner apps. If you release your mini program to Alipay China, refer to the Alipay China 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+ partner apps) 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

Finish the steps below to get boarded and configure public keys for signature:

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.

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 steps in the diagram are described as follows:

1. A user opens the merchant's mini program. The mini program invokes my.getAuthCode(scopes) to send an authorization request to the super app [1.1].
2. The super app processes the request and then pops up the authorization page [1.1.1].
3. After the user agrees to the authorization, the mini program gets authCode [2.1].
4. Then the mini program calls my.getAppIdSync and gets appId from the super app [2.1.2].
5. The mini program calls my.getSiteInfo and gets customerBelongsTo from the super app [2.1.4].

You can obtain user authorization by calling the my.getAuthCode JSAPI and fetch the authCode in the success callback. To learn more, see my.getAuthCode.

Note: 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 the accessToken [1.3].
5. The merchant server validates the signature, creates a login session, and then saves the 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 and revoke authorization.

Step 3: (Optional) Query user information

You can decide which kind of information you want to inquire about depending on your business requirements. User information includes userId, status, nickName, userName, avatar, gender, birthDate, loginIdInfos, contactInfos, 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].

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

Step 4: (Optional) Revoke authorization

You can cancel the authorization by calling the revoke API. For more about this API, refer to /v2/authorizations/revoke.

The following sequence diagram illustrates how to cancel the authorization via the revoke API:

When a user cancels an access token from the mini program,

1. The merchant server calls the revoke API via /v2/authorizations/revoke to cancel the access token [1.1].
2. AIMPDP processes the cancellation request and returns the result to the merchant server [1.2].
3. Then the merchant server transfers the result to the mini program [1.3].

API list

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

JSAPI

OpenAPI

More information

Alipay China user authorization solution

Alipay+ merchant onboarding

Alipay technical support