/v1/authorizations/applyToken

POST /v1/authorizations/applyToken

The applyToken interface is used to obtain the access token. This interface can be used in the following cases:

  • After the merchant receives authCode from Mini-Program, the merchant uses this interface to request the access token from e-wallet. In this scenario, the interface generally needs to be used with the Authorization Prepare Interface.
  • When the original token expires, the merchant requests a new access token by using the refresh token. In this scenario, this interface can be used independently.

Message structure

Request

Property

Data type

Required

Description

referenceClientIdString

No

In Mini-Program scenario, it is the unique identifier of the Mini-Program authorized by the user.

 

The referenceClientId represents the next-level clien id. When multiple auth codes need to be assigned to the same client, different referenceClientIds can be passed in to distinguish them.

Max. length: 128 characters.

grantType

String

Yes

Indicates which parameter is to be used to obtain the access token. Possible values are:

  • AUTHORIZATION_CODE: the authCode  is to be used to retrieve the accessToken.
  • REFRESH_TOKEN: the refreshToken is to be used to retrieve the accessToken.

Max. length: 16 characters.

authCode

String

No

Is required when grantType is AUTHORIZATION_CODE.

The authorization code, which is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the Mini-program API, the Mini-program will get the authorization code from the response of and use it to request an access token.

Max. length: 32 characters.

refreshToken

String 

No

refreshToken is required when grantType is REFRESH_TOKEN.

The refresh token, which is used by the auth client to exchange for a new access token when the access token expires. By using the refresh token, new access tokens can be obtained without further interaction with the user.

Max. length: 128 characters.

extendInfoString 

No

The extend information,wallet and merchant can put extend info here.

Max. length: 4096 characters.

Response

Property

Data type

Required

Description

result

Result

Yes

The request result, which contains information related to the request result, such as status and error codes.

accessToken

String 

No

An access token that can be used to access the user resource scope.

When authorization application is successful [result.resultStatus == S], the auth client might use accessToken to acccess the corresponding user's resource scope.

Max. length: 128 characters.

    accessTokenExpiryTime

    String/Datetime

    No

    Access token expiration time, which follows the ISO 8601 standard. After this time, authClient will not be able to use this token to deduct from user's account.

    This parameter must be returned when authorization application is successful [result.resultStatus == S],  and the accessToken will be invalid after 

    accessTokenExpiryTime.

    refreshToken

    String 

    No

    The refresh token that is used by the auth client to exchange for a new access token when the access token expires. By using the refresh token, new access tokens can be obtained without further interaction with the user.

    This parameter must be returned when authorization application is successful [result.resultStatus == S], and the merchant can use the refreshToken to request for a new accessToken.

    Max. length: 128 characters.

    refershTokenExpiryTime

    String/Datetime

    No

    Refresh token expiration time, after which the auth client cannot use this token to retrieve a new access token. The value follows the ISO 8601 standard.

    This parameter must be returned when authorization application is successful [result.resultStatus == S],  and the merchant will not be able to use the refreshToken to retrieve a new accessToken after refreshTokenExpiryTime.

    customerId

    String

    No

    Resource owner id, maybe user id, app id of merchant's application, merchant id.

    Max. length: 64 characters.

    extendInfoString 

    No

    The extend information,wallet and merchant can put extend info here.

    Max. length: 4096 characters.

    Result process logic

    For different request results, different actions are to be performed. See the following list for details:

    • If the value of result.resultStatus is S, the authorization token application request is successful. The merchant can use the access token to access the corresponding user resource scope.
    • If the value of result.resultStatus is F or U, AuthClient may guide user to try again.

    Result

    resultStatus

    resultCoderesultMessage
    SSUCCESSSuccess.
    UUNKNOWN_EXCEPTIONAn API calling is failed, which is caused by unknown reasons.
    UREQUEST_TRAFFIC_EXCEED_LIMITThe request traffic exceeds the limit.
    FPROCESS_FAILA general business failure occurred. Don't retry.
    FPARAM_ILLEGALIllegal parameters exist. For example, a non-numeric input, or an invalid date.
    FACCESS_DENIEDThe access is denied.
    FINVALID_APIThe called API is invalid or not active.
    FAUTH_CLIENT_UNSUPPORTED_GRANT_TYPE

    The auth client do not support this grant type.

    FINVALID_AUTH_CLIENT

    The auth client is invalid.

    FINVALID_AUTH_CLIENT_STATUS

    Invalid auth client status.

    FINVALID_REFRESH_TOKENThe refresh token is invalid.
    FEXPIRED_REFRESH_TOKENThe refresh token is expired.
    F

    USED_REFRESH_TOKEN

    The refresh token has been used.
    FINVALID_CODEThe authorization code is invalid.
    F

    USED_CODE

    The authorization code has been used.

    F

    EXPIRED_CODE

    The authorization code is expired.
    FREFERENCE_CLIENT_ID_NOT_MATCH

    The reference client id does not match.

    F

    EXPIRED_AGENT_TOKEN

    The access token of mini program is expired.

    F

    INVALID_AGENT_TOKEN

    The access token of mini program is invalid.

    Sample

    The authorization token application is used to exchange the access token based on the auth code after obtaining the auth code.

    /v1/authorizations/applyToken
    1. The Mini Program calls my.getAuthCode interface to obtain the authorization code from e-wallet. (Step 1)
    2. E-wallet returns the authorization code to the Mini Program (Step 7)
    3. The Mini Program sends authorization code to the merchant server (Step 8)
    4. The merchant server calls /v1/authorizations/applyToken interface to obtain the access token from e-wallet server and e-wallet server returns the access token and customer ID to the merchant server (Step 9 and Step 11).

    Note: Other steps are covered by e-wallet.

    Request

    A. Retrieving accessToken with authCode

    copy
    {
        "grantType": "AUTHORIZATION_CODE",
        "authCode": "20210727fu6BglGjFqZ0883600107690",
        "extendInfo": "{\"customerBelongsTo\":\"TNG\"}"
    }

    B. Retrieving accessToken with refreshToken

    copy
    {
      "grantType": "REFRESH_TOKEN",
      "refreshToken": "2810111301lGZcM9CjlF91WH00039190xxxx",
      "extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
    }
    • authCode is from the my.getAuthCode JS-API, you can obtain the authCode  in the success callback. when grantType == AUTHORIZATION_CODE means that we are requesting for the accessToken by the authCode .
    • refreshToken is obtained from the response of the previous accessToken Application call. while grantType == REFRESH_TOKEN means that we are requesting for the accessToken by providing the refreshToken.
    • extendInfo, includes key - customerBelongsTo the e-wallet that the customer uses. Corresponding to the field 'siteName' that obtained from the API 'my.getSiteInfo', in the Mini Program scenario this is mandatory.

    Response

    copy
    {
        "accessToken": "20210727SZUjLZhgkNWB44c4ull4pg9FFdQzjcOSO6I8uGNSCLS0883600107692",
        "accessTokenExpiresIn": "0",
        "accessTokenExpiryTime": "2021-08-01T13:04:59+08:00",
        "customerId": "1000000840500000",
        "refreshToken": "2021072716a5T2ALneGTtSMLCW0cd9rsQZYD8ErB7NGXvLGptHt0883600107693",
        "refreshTokenExpiresIn": "0",
        "refreshTokenExpiryTime": "2021-08-01T13:04:59+08:00",
        "result": {
            "resultCode": "SUCCESS",
            "resultMessage": "success.",
            "resultStatus": "S"
        }
    }
    • result.resultStatus==S shows that the application is successful,
    • AuthClient can make use of accessToken to access the user's resource scope before 2019-06-06T12:12:12+08:00[accessTokenExpiryTime].
    • AuthClient  can make use of refreshToken to request for a new accessToken before 2019-06-08T12:12:12+08:00[refreshTokenExpiryTime].