/v2/authorizations/applyToken

2023-08-02 02:43

POST /v2/authorizations/applyToken

With this API call, a merchant can obtain an access token from the super app. The merchant is then authorized by users to provide services on the mini program.

Note:

Before calling this API, call the my.getAuthCode JSAPI to obtain an authorization code from the super app as the request parameter. Then call this API to exchange for an access token from the super app.
When the original access token expires, use the refresh token to exchange for a new access token directly. In this scenario, this API can be used independently.
An access token should be kept in the merchant server only, which means it should not be returned to the mini program.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
appId	String	Yes	Indicates the unique ID assigned by Mini Program Platform to identify a mini program. Maximum length: 32 characters Characters not allowed: special characters such as @ # ? Note: Obtain this field via Mini Program Platform.	"3333010071465913xxx"
authClientId	String	Yes	Indicates the unique ID assigned by the super app to identify an authorized merchant. Maximum length: 128 characters Characters not allowed: special characters such as @ # ?	"202016726873874774774xxxx"
grantType	String	Yes	Indicates the way the authorized merchant obtains an access token. Valid values are: AUTHORIZATION_CODE: Exchange for an access token. REFRESH_TOKEN: Exchange for a new access token when the original one expires.	"AUTHORIZATION_CODE"
authCode	String	No	The authorization code is used to exchange for an access token. Mini programs can obtain an authorization code via the my.getAuthCode JSAPI and then send it to the merchant. Then the merchant is authorized to use the authorization code to exchange for an access token. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be Null. Note: This field is required when the value of grantType is AUTHORIZATION_CODE.	"2810111301lGZcM9CjlF91WH00039190xxxx"
refreshToken	String	No	The refresh token is used to exchange for a new access token when the original one expires. With the refresh token, a new access token can be obtained without further interaction with the user. Maximum length: 128 characters Characters not allowed: special characters such as @ # ? Can be Null. Note: This field is required when the value of grantType is REFRESH_TOKEN.	"2810111301lGZcM9CjlF91WH00039190xxxx"

Response parameters

Field	Data type	Required	Description	Example
result	Result	Yes	Indicates the request result such as status and error codes.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage":"success" }
accessToken	String	No	The access token is used to access user information. For the specific information that can be accessed, see the my.getAuthCode JSAPI. Maximum length: 128 characters Characters not allowed: special characters such as @ # ? Can be Null. Note: This field must be returned when the authorization request is successful.	"281010033AB2F588D14B43238637264FCA5AAF35xxxx"
accessTokenExpiryTime	Long	No	Indicates when an access token expires.For example, in the payment scenario, once the access token expires, the authorized merchant cannot use this token to debit the user's account. The value would be the timestamp. Note: This field must be returned when the authorization request is successful.	1682058090533
refreshToken	String	No	The refresh token is used to exchange for a new access token when the original one expires. With the refresh token, a new access token can be obtained without further interaction with the user. Maximum length: 128 characters Characters not allowed: special characters such as @ # ? Can be Null. Note: This field must be returned when the authorization request is successful.	"2810100334F62CBC577F468AAC87CFC6C9107811xxxx"
refreshTokenExpiryTime	Datetime	No	Indicates when the refresh token expires. Once the refresh token expires, the authorized merchant cannot use this token to exchange for a new access token. The value would be the timestamp. Note: This field must be returned when the authorization request is successful.	1682058090533
userId	String	Yes	UserId	"1000001119398804xxxx"

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	The authorization request is successful. The corresponding result.resultCode is SUCCESS and the result.resultMessage is SUCCESS.
U	The status of the authorization request is unknown. The corresponding result.resultCode is UNKNOWN_EXCEPTION and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The authorization request is failed. The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for all mini program OpenAPIs in V2.
API-specific error codes are listed in the following table.

Error code	Result status	Error message	Further action
INVALID_AUTH_CLIENT	F	Either the authorized merchant does not exist or the merchant does not onboard to the native app.	Use a valid authClientId assigned by the super app.
INVALID_REFRESH_TOKEN	F	The refresh token does not exist.	Obtain a new refresh token via this API.
EXPIRED_REFRESH_TOKEN	F	The refresh token expires.	Obtain a new authorization code from the super app via the my.getAuthCode JSAPI and then obtain a new refresh token via this API.
INVALID_AUTHCODE	F	The authorization code does not exist.	Obtain a new authorization code from the super app via the my.getAuthCode JSAPI.

Samples

The data flow to obtain an access token is illustrated as below:

The mini program calls the my.getAuthCode JSAPI to request an authorization code from the super app.
The super app processes the request and shows the information that needs to be authorized.
The user confirms the authorization in the super app.
The super app service processes the authorization information to the super app server.
The super app server verifies the authorization information and then generates the authorization code.
The super app server returns the authorization code to the super app service.
The super app service returns the authorization code to the mini program.
The mini program sends the authorization code to the merchant server.
The merchant server calls this API to exchange for an access token from the super app server.
The super app server verifies the authorization code and generates the access token.
The super app returns the access token to the merchant server.

Request

Use an authorization code to exchange for an access token

copy
{
  "appId":"3333010071465913xxx",
  "authClientId": "202016726873874774774xxxx",
  "grantType": "AUTHORIZATION_CODE",
  "authCode": "2810111301lGZcM9CjlF91WH00039190xxxx"
}

The mini program (3333010071465913xxx) calls the my.getAuthCode JSAPI to obtain the authorization code (2810111301lGZcM9CjlF91WH00039190xxxx) and then send the authorization code to the merchant (202016726873874774774xxxx). The merchant uses the authorization code to exchange for an access token as grantType is AUTHORIZATION_CODE.

Use a refresh token to exchange for an access token

copy
{
  "appId":"3333010071465913xxx",
  "authClientId": "202016726873874774774xxxx",
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "2810111301lGZcM9CjlF91WH00039190xxxx"
}

The value of grantType is REFRESH_TOKEN, which means the merchant can obtain an access token by the refresh token (2810111301lGZcM9CjlF91WH00039190xxxx).

Response

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uS2V5IjoiM2U5YmMzZmItNmI0Yy00MzA1LTlhZTgtNGJlNmRiOTU0NTE2IiwidXNlcl9uYW1lIjoiVXNlclByb2ZpbGVWbyhpZD0yMDQzLCB0ZW5hbnRJZD0xLCB1c2VySWQ9MjA0MywgdXNlckNvZGU9Y2Q5NDZmODkzMzQxMjYzLCBlbWFpbD1udWxsLCBwd2Q9bnVsbCwgZWZmZWN0aXZlRGF0ZT1udWxsLCBleHBpcnlEYXRlPW51bGwsIGxvZ2luRmFpbD1udWxsLCBzdGF0dXM9bnVsbCwgY3JlYXRlQnk9bnVsbCwgY3JlYXRlRGF0ZT1udWxsLCB1cGRhdGVEYXRlPW51bGwsIG5lZWRDaGFuZ2VQYXNzd29yZD1udWxsLCBjdXN0b21lclByb2ZpbGU9bnVsbCwgdXNlclR5cGU9bnVsbCwgY3VzdG9tZXJJZD1udWxsLCB1c2VyUG9ydHJhaXRQcm9maWxlPW51bGwsIGdyb3VwSWQ9bnVsbCwgcGhvbmVOdW1iZXI9MTM0NTY4OTYyNSwgdXNlclByb2ZpbGVEZXRhaWxWbz1Vc2VyUHJvZmlsZURldGFpbFZvKHVzZXJJZD0yMDQzLCB1c2VyQ29kZT1jZDk0NmY4OTMzNDEyNjMsIG5pY2tOYW1lPTEzNCoqKioqMjUsIGdlbmRlcj1udWxsLCBmYWNlVXJsPW51bGwsIG1haW5PcmdOYW1lPW51bGwsIHVzZXJTdGF0ZT1BLCBlbWFpbD1udWxsLCBwaG9uZU51bWJlcj0xMzQ1Njg5NjI1LCB1c2VyTmFtZT0xMzQ1Njg5NjI1LCB0ZW5hbnRJZD0xLCBjdXN0b21lckluZm89bnVsbCwgZ3JhZGVOYW1lPW51bGwsIGdyb3d0aFZhbD1udWxsKSwgdXNlck9yZ1Byb2ZpbGVMaXN0PVtdLCBkb21haW5JZExpc3Q9bnVsbCwgY291bnRyeVBob25lQ29kZT1udWxsLCB1c2VyTmFtZT0xMzQ1Njg5NjI1LCBuaWNrTmFtZT0xMzQqKioqKjI1LCBzZW5kQWN0aXZlU21zPW51bGwsIHNlbmRBY3RpdmVFbWFpbD1udWxsLCBpbnB1dEZhaWw9bnVsbCwgY29tbWVudHM9bnVsbCwgYXZhdGFyPW51bGwsIGxvY2tUaW1lPW51bGwsIHVwZGF0ZUJ5PW51bGwsIHN0YWZmQ29kZUxpc3Q9bnVsbCwgc3RhZmZQcm9maWxlTGlzdD1udWxsLCBleHRJbmZvPW51bGwsIGxvY2tTdGF0ZT1udWxsKSIsInNjb3BlIjpbIlVzZXJfQ3VzdG9tZXJfS1lDX0luZm8iXSwiZXhwIjoxNjkxMDI3NjM2LCJ0b2tlblR5cGUiOm51bGwsInVzZXJJZCI6IjIwNDMiLCJqdGkiOiJ6bWNvdE9KQWRmbWEwXzBvcDJqaURIbHVpaTgiLCJjbGllbnRfaWQiOiIyMDIzMDcwNzAyMDgwMDAxIn0.sSHcVDh1t1g3jG3W325yfjlClMSh5Phok00NO7Jt-6c",
    "accessTokenExpiryTime": "1691027636291",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uS2V5IjoiM2U5YmMzZmItNmI0Yy00MzA1LTlhZTgtNGJlNmRiOTU0NTE2IiwidXNlcl9uYW1lIjoiVXNlclByb2ZpbGVWbyhpZD0yMDQzLCB0ZW5hbnRJZD0xLCB1c2VySWQ9MjA0MywgdXNlckNvZGU9Y2Q5NDZmODkzMzQxMjYzLCBlbWFpbD1udWxsLCBwd2Q9bnVsbCwgZWZmZWN0aXZlRGF0ZT1udWxsLCBleHBpcnlEYXRlPW51bGwsIGxvZ2luRmFpbD1udWxsLCBzdGF0dXM9bnVsbCwgY3JlYXRlQnk9bnVsbCwgY3JlYXRlRGF0ZT1udWxsLCB1cGRhdGVEYXRlPW51bGwsIG5lZWRDaGFuZ2VQYXNzd29yZD1udWxsLCBjdXN0b21lclByb2ZpbGU9bnVsbCwgdXNlclR5cGU9bnVsbCwgY3VzdG9tZXJJZD1udWxsLCB1c2VyUG9ydHJhaXRQcm9maWxlPW51bGwsIGdyb3VwSWQ9bnVsbCwgcGhvbmVOdW1iZXI9MTM0NTY4OTYyNSwgdXNlclByb2ZpbGVEZXRhaWxWbz1Vc2VyUHJvZmlsZURldGFpbFZvKHVzZXJJZD0yMDQzLCB1c2VyQ29kZT1jZDk0NmY4OTMzNDEyNjMsIG5pY2tOYW1lPTEzNCoqKioqMjUsIGdlbmRlcj1udWxsLCBmYWNlVXJsPW51bGwsIG1haW5PcmdOYW1lPW51bGwsIHVzZXJTdGF0ZT1BLCBlbWFpbD1udWxsLCBwaG9uZU51bWJlcj0xMzQ1Njg5NjI1LCB1c2VyTmFtZT0xMzQ1Njg5NjI1LCB0ZW5hbnRJZD0xLCBjdXN0b21lckluZm89bnVsbCwgZ3JhZGVOYW1lPW51bGwsIGdyb3d0aFZhbD1udWxsKSwgdXNlck9yZ1Byb2ZpbGVMaXN0PVtdLCBkb21haW5JZExpc3Q9bnVsbCwgY291bnRyeVBob25lQ29kZT1udWxsLCB1c2VyTmFtZT0xMzQ1Njg5NjI1LCBuaWNrTmFtZT0xMzQqKioqKjI1LCBzZW5kQWN0aXZlU21zPW51bGwsIHNlbmRBY3RpdmVFbWFpbD1udWxsLCBpbnB1dEZhaWw9bnVsbCwgY29tbWVudHM9bnVsbCwgYXZhdGFyPW51bGwsIGxvY2tUaW1lPW51bGwsIHVwZGF0ZUJ5PW51bGwsIHN0YWZmQ29kZUxpc3Q9bnVsbCwgc3RhZmZQcm9maWxlTGlzdD1udWxsLCBleHRJbmZvPW51bGwsIGxvY2tTdGF0ZT1udWxsKSIsInNjb3BlIjpbIlVzZXJfQ3VzdG9tZXJfS1lDX0luZm8iXSwiYXRpIjoiem1jb3RPSkFkZm1hMF8wb3AyamlESGx1aWk4IiwiZXhwIjoxNjkzNTMzMjM2LCJ0b2tlblR5cGUiOm51bGwsInVzZXJJZCI6IjIwNDMiLCJqdGkiOiJvd1QwcjlMd1BpUF9TT19TZEtBSVBVMUpSQUUiLCJjbGllbnRfaWQiOiIyMDIzMDcwNzAyMDgwMDAxIn0.kAJlRtsHANdlSQ8tGGp-u0k8bWRHIuyTxRGnwwJAtY0",
    "refreshTokenExpiryTime": "1691027636291",
    "userId": "1000001119398804xxxx"
}

result.resultStatus is S, which shows the request to obtain an access token is successful.
The authorized merchant can use the access token (281010033AB2F588D14B43238637264FCA5AAF35xxxx) before accessTokenExpiryTime (2019-06-06T12:12:12+08:00).
1000001119398804xxxx is the user who authorizes the merchant.
The authorized merchant can use the refresh token (2810100334F62CBC577F468AAC87CFC6C9107811xxxx) to exchange for a new access token before refreshTokenExpiryTime (2019-06-08T12:12:12+08:0).