Authentication

Overview

This flow covers the user authentication process in Mini Programs, enabling merchants to obtain user authorization and access tokens. The flow consists of two key steps: requesting an authorization code via my.getAuthCode and exchanging it for access tokens via applyToken. These tokens allow merchants to access user data and perform authorized operations.

Flow Steps

Authorization Request Phase

1. The Mini Program calls the my.getAuthCode JSAPI with specific scopes to request an authorization code.
2. The E-wallet App processes the request and displays the authorization page that needs to be authorized.
3. The user confirms the authorization in the super app.
4. The E-wallet App service calls authorization service to processes the authorization information.
5. The E-wallet backend verifies the authorization information, generates the authCode and returns.
6. The E-wallet App service returns the authCode to the Mini Program.
7. The Mini Program sends the authCode to the merchant backend.
8. The merchant backend calls the applyToken API with authCode to apply the accessToken.
9. The E-Wallet backend returns accessToken information to the merchant backend, such as accessToken, refreshToken, etc.

Token Exchange Phase

After obtaining the authorization code, the merchant exchanges it for access tokens:

1. Request Authorization Code (my.getAuthCode) The Mini Program initiates the authentication flow by calling my.getAuthCode with the required scopes. This JSAPI prompts the user (if needed) and returns an authCode that represents the user's consent.

For more details, check the my.getAuthCode documentation.

2. Exchange for Access Token (applyToken) The merchant backend securely exchanges the authCode for access tokens by calling POST /v1/authorizations/applyToken. This endpoint returns an accessToken, refreshToken, and customerId which are used for subsequent API calls.

For more details, check the applyToken endpoint documentation.

3. Token Refresh (applyToken with REFRESH_TOKEN) When the accessToken expires, merchants can obtain a new token without user interaction by calling applyToken with grantType: REFRESH_TOKEN and the stored refreshToken. This maintains seamless user experience without re-authorization.

For more details, check the applyToken endpoint documentation.

Authorization Code Request

my.getAuthCode Parameters

my.getAuthCode({
  scopes: ['USER_ID'],
  success: (res) => {
    // Send res.authCode to merchant backend
    my.request({
      url: 'https://merchant.com/api/auth',
      method: 'POST',
      data: {
        authCode: res.authCode
      }
    });
  },
  fail: (err) => {
    console.log('Authorization failed:', err.authErrorScopes);
  }
});

Available Scopes

For the complete, authoritative list of scopes — covering both Customer User and Business (Merchant) User scopes and which support silent authorization — see the Scope Reference in getAuthCode.

Success Response

{
  "authCode": "0000000001T1dc0W0tv44B0BD00007826",
  "authSuccessScopes": ["USER_ID"]
}

Failure Response

{
  "authErrorScopes": {
    "auth_user": "10001"
  }
}

Token Exchange Request

applyToken Request Structure

POST /v1/authorizations/applyToken
Content-Type: application/json

{
  "grantType": "AUTHORIZATION_CODE",
  "authCode": "2810111301lGzcM9CjlF91WH00039190xxxx"
}

Field Notes

• grantType: Use AUTHORIZATION_CODE to exchange an authCode, or REFRESH_TOKEN to refresh an expired access token.
• authCode: The authorization code obtained from my.getAuthCode (required when grantType is AUTHORIZATION_CODE).
• refreshToken: The refresh token from a previous applyToken call (required when grantType is REFRESH_TOKEN).
• extendInfo: Optional JSON string for additional metadata (max 4096 characters).

Token Exchange Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
  "accessTokenExpiryTime": "2023-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811xxxx",
  "refreshTokenExpiryTime": "2023-06-08T12:12:12+08:00",
  "customerId": "1000001119398804xxxx"
}

Response Interpretation

• result.resultStatus = S: token exchange successful; store the tokens and customerId securely.
• result.resultStatus = U: unknown exception; retry the request or check server logs.
• result.resultStatus = F: exchange failed. Inspect result.resultCode (e.g., INVALID_CODE, EXPIRED_CODE, USED_CODE) and handle accordingly.

Response Fields

• accessToken: Token used to authenticate API requests on behalf of the user. Has a shorter lifespan.
• accessTokenExpiryTime: ISO 8601 timestamp indicating when the access token expires.
• refreshToken: Token used to obtain a new access token without user interaction.
• refreshTokenExpiryTime: ISO 8601 timestamp indicating when the refresh token expires.
• customerId: Unique identifier for the user; use this as referenceBuyerId in payment requests.

Token Refresh Request

When the accessToken expires, use the refresh token to obtain a new one:

POST /v1/authorizations/applyToken
Content-Type: application/json

{
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "2810110033AAB2F588D14B43238637264FCA5AAF35xxxx"
}

Common Error Codes

my.getAuthCode Errors

applyToken Errors

Related APIs

• my.getAuthCode
• applyToken
• prepare
• qicardSignContract