All Products
Document Center

Access Account authorization in server-side

Last Updated: Mar 24, 2021

The Account authorization service is used to obtain and access Alipay-related services such as authorization and payment on non-Alipay clients. In addition to accessing the relevant SDK on the client, the accessing party also needs to implement relevant services on the server to complete the Alipay third-party authorization process. The Alipay third-party authorization process is as follows.


The server access process includes the following steps:

  1. Create an app.
  2. Generate an authorization link.
  3. Obtain access_token and Alipay user_id.
  4. Synchronize the account binding relationship

Create an app

Before access, you must create, configure, and launch an app on the Alipay open platform. For details, see Create an app.

Creation instructions:

  • When you create the app, select Custom access and select Mobile app for the app type.
  • Add app functions and select Obtain member information.
  • The entered authorized callback address must be consistent with the callback address used in the subsequent access.

Generate an authorization request link

To help developers call Alipay’s open platform APIs, we provide an open-platform server SDK to encapsulate basic functions such as signature verification and HTTP requests. You can download the required language version by visiting Server SDKs. This topic uses the Java version of SDK as an example.

Constructing the authorization request link consists of two steps:

  1. Initialize API calls.
  2. Construct service request parameters.

Initialize API calls

The relevant code is as follows:

  1. AlipayClient alipayClient = new DefaultAlipayClient(ALIPAY_GATEWAY_URL, APP_ID,

The parameters are described as follows:

Parameter Description Parameter value or acquisition method
ALIPAY_GATEWAY_URL The Alipay gateway, which is a fixed value. A fixed value, which is
APP_ID The AppID obtained when the app is created. For details, see Create an App > View the AppID.
APP_PRIVATE_KEY The developer’s private key, which is generated by the developer. For details, see Create an App > Configure the App Environment.
FORMAT The return format of parameters, which only supports JSON. A fixed value, which is json.
CHARSET The encoding format, which supports GBK and UTF-8. Select GBK or UFT-8 as needed.
ALIPAY_PUBLIC_KEY The Alipay public key. For details, see Generate a public key.
SIGN_TYPE The type of the algorithm used by the developer to generate the signature, which supports RSA and RSA2. The recommended value is RSA2. RSA2

Construct service request parameters

Parameter Required Description
return_url Yes The callback address, which must be consistent with the callback address that you set when configuring the app.
scopes Yes The API permission value, such as auth_user or auth_base. The request format is "scopes":["auth_user","auth_base"].
state Yes
  • A custom parameter. After user authorization, the value of this parameter will be returned to the developer as is when you are redirected to redirect_uri.
  • To prevent CSRF attacks, we recommend developers to import the state parameter when requesting authorization. This parameter should be unpredictable and can prove that the logon authentication state of the client is related to that of the current third-party website.
  • Only Base64 characters (with a length no greater than 100 bits) are allowed.
auth_type Yes This parameter is used to identify the authorization type. The value is MY_PASS_OAUTH.
origin Yes The call source, which is a host ID assigned by us.
is_mobile Yes true

Code sample

  1. AlipayClient alipayClient = new DefaultAlipayClient("", appId, appPrivateKey, "json", "UTF-8", alipayPublicKey, "RSA2");
  2. // Create a request for the API.
  3. AlipayUserInfoAuthRequest alipayRequest = new AlipayUserInfoAuthRequest();
  4. // Set the authorization callback address, which is configured in the background of the open platform.
  5. alipayRequest.setReturnUrl("Authorization callback URL");
  6. // Construct a scope list.
  7. List<String> scopes = new ArrayList<String>();
  8. scopes.add("auth_base");
  9. scopes.add("auth_user");
  10. Map<String, Object> bizContent = new HashMap<String, Object>();
  11. bizContent.put("scopes", scopes);
  12. bizContent.put("auth_type", "MY_PASS_OAUTH"); // A fixed value.
  13. bizContent.put("origin", "XXXX"); // The call source, such as AMAP, UC_BROSWER, or NAPOS.
  14. bizContent.put("is_mobile", "true"); // A fixed value.
  15. // The unique random identifier of the request for preventing CSRF attacks. Only Base64 characters (with a length no greater than 100 bits) are allowed.
  16. bizContent.put("state", "xxxxxx");
  17. // Specify service parameters.
  18. alipayRequest.setBizContent(JSONObject.toJSON(bizContent).toString());
  19. AlipayUserInfoAuthResponse response = alipayClient.pageExecute(alipayRequest, "GET");
  20. if (response.isSuccess()) {
  21. System.out.println("Called successfully");
  22. System.out.println(response.getBody());
  23. } else {
  24. System.out.println("Failed to call");
  25. System.out.println(response.getSubCode() + ":" + response.getSubMsg());
  26. }

An example of the generated authorization link is as follows:

This authorization link can be reused, and the client uses this authorization link to initiate an authorization request to Alipay to obtain auth_code.

Obtain access_token and Alipay user_id

Obtain access_token and Alipay user_id through the alipay.system.oauth.token API.

A sample API call is as follows:

  1. AlipayClient alipayClient = new DefaultAlipayClient("", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
  2. AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
  3. request.setCode("2e4248c2f50b4653bf18ecee3466UC18");
  4. request.setGrantType("authorization_code");
  5. try {
  6. AlipaySystemOauthTokenResponse oauthTokenResponse = alipayClient.execute(request);
  7. System.out.println(oauthTokenResponse.getAccessToken());
  8. } catch (AlipayApiException e) {
  9. e.printStackTrace();
  10. }

Synchronize the account binding relationship

After you obtain access_token and Alipay user_id, you need to further call the synchronization API of the account binding relationship to bind the unique identifier of the organization with Alipay user_id.

Define the API

  • A binding failure affects the creation of the logon state, preventing users from accessing the service.
  • Due to network timeout or other reasons, if the API returns a timeout or unknown exception, the accessing party must retry until succeeds.
Description Save account binding relationships, including addition, deletion, and modification.
Description of input parameters
  • userId: The UserId of the accessing party.
  • userSource: The site name of the accessing party, which is assigned by us.
  • alipayUserId: The Alipay user ID to be bound.
  • userOccupiedAutoDelete: The value is true or false. If the user has been bound by another Alipay user, the existing relationship will be deleted automatically, which is valid only when opType=enable.
  • alipayUserOccupiedAutoDelete: The value is true or false. If the Alipay user has been bound by another accessing site user, the existing relationship will be deleted automatically, which is valid only when opType=enable.
  • opType: The operation type, which can be enable or delete. The enable value indicates storage, and the delete value indicates deletion.
Description of output parameters
  • code: The result code.
  • msg: The result information.

Code sample of calling

  1. AlipayClient alipayClient = new DefaultAlipayClient("","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
  2. AlipayUserAntpaasRoleRelationSaveRequest request = new AlipayUserAntpaasRoleRelationSaveRequest();
  3. request.setBizContent("{" +
  4. "\"user_id\":\"287346876344\"," +
  5. "\"user_source\":\"FINTECH_TEST\"," + "\"alipay_user_id\":\"2088131231323456\"," +
  6. "\"op_type\":\"enable\"," +
  7. "\"user_occupied_auto_delete\":true," + "\"alipay_user_occupied_auto_delete\":true" +
  8. " }");
  9. AlipayUserAntpaasRoleRelationSaveResponse response = alipayClient.execute(request);
  10. if (response.isSuccess()) {
  11. System.out.println("Called successfully");
  12. } else {
  13. System.out.println("Failed to call");
  14. }