User authorization

2023-04-28 21:00

User authorization describes the process of obtaining a user's consent to access user information. It is based on the industry standard OAuth2.0 authorization mechanism. On the Mini Program Platform, developers need to get permission from users in the mini program before obtaining and using their information.

Terminology

Name	Description
Scope of authorization (scope)	A scope represents the scope of permissions that developers need to request user authorization. A scope contains at least one open API interface or JSAPI interface. One authorization can combine multiple scopes for combined authorization.
Authorization code (auth_code)	Temporary user authorization credentials. After obtaining it, promptly exchange it for the access token mentioned below.
Access token or authorization token (access_token or auth_token)	Long-term authorization credentials. It is used to call the site gateway to call the server-side authorization interface. Pay attention to the scope and validity of the authorization token.
Refresh token (refresh_token)	Used to refresh and obtain a new access token after the access token expires. The refresh token also has a validity period.

Scope list

Scope	Description
USER_ID	Authorized to obtain the unique user ID.
USER_NICKNAME	Authorized to obtain the user nickname.
USER_NAME	Authorized to obtain the user name.
USER_LOGIN_ID	Authorized to obtain the user's login ID.
HASH_LOGIN_ID	Authorized to obtain the hash user login ID.
USER_AVATAR	Authorized to obtain the user avatar.
USER_GENDER	Authorized to obtain the user's gender.
USER_BIRTHDAY	Authorized to obtain the user's birthday.
USER_NATIONALITY	Authorized to obtain the user's nationality.
USER_CONTACTINFO	Authorized to obtain the user's contact information.
auth_base	Authorized to obtain the unique user ID.
auth_user	Authorized to obtain the user information.

Access guidelines

Access process

Take obtaining the user information as an example. The overall access process is illustrated as below:

The mini program calls the getAuthCode JSAPI to get the authorization code (authCode) from the wallet [1.1].
The mini program calls the merchant server API with authCode [2].
The merchant server calls the applyToken OpenAPI and the authorized platform server returns the access token [2.2].
The merchant server saves the access token and returns the authorization result to the mini program [2.4].

Note: To authorize other information, use a different scope for the scopes parameter when calling getAuthCode.

Obtain authCode

You can obtain user authorization by calling the my.getAuthCode JSAPI and fetch the authCode in the success callback. For example:

copy
my.getAuthCode({
  scopes: ['USER_ID'],
  success: (res) => {
    my.alert({
      content: res.authCode,
    });
  },
  failed: (res) => {
      console.log(res.authErrorScopes)
  },
});

Obtain accessToken

For merchants: Before obtaining an accessToken, you need to get an authCode from the wallet. Then you can call the applyToken OpenAPI in exchange for accessToken.
For developers: Developers can exchange accessToken and userId with the obtained authCode.

Call the server OpenAPI

After obtaining the accessToken, developers can continue to use the access token to call other authorization interfaces. Pay attention to the permission scope and validity period of the token.

API List

JSAPI	Description
my.getAuthCode	Gets user's authorization code.
OpenAPI	Description
v2/authorizations/applyToken	Obtain the access token.

FAQs

1. Why should developers use my.getAuthCode API?

All the reading and writing of user information on the Mini Program Platform can only be used after obtaining the user's consent. User authorization is based on the industry standard OAuth2.0 authorization mechanism. With this mechanism, developers can obtain user information on the Mini Program Platform.

2. Why is the user authorization API not allowed on the first screen of the mini program?

In order to create a better user experience on the mini program, user authorization guidance is not allowed on the first screen of the mini program. The guidance for user authorization should be given after the user fully understands the business content of the mini program. We recommend you add the mini program authorization into the business process.

3. Can userId be obtained through the user authorization API?

No, the userId needs to be obtained by calling the related API on the server side.

More information

Obtain basic user information