The access_token is the globally unique credential for calling APIs on Official Accounts. It is required for calls to all APIs on Official Accounts, and developers need to save it properly. To store access_token, you need to reserve space for at least 512 characters. The access_token is valid for 2 hours and needs to be updated periodically. Repeated acquisition will invalidate the access_token obtained last time.

Use and generation of the access_token required for calling APIs on the Official Accounts Platform:

  1. It is recommended to obtain and update access_token by using a central control server. All the access_token values used by other business logic servers come from this central control server and should not be updated separately. Otherwise, access_token may be overwritten, which affects services.

  2. The validity period of access_token is expressed in the returned expire_in, and its available value is within 7200 seconds. The central control server needs to update access_token in advance based on this validity period. During the update, the central control server may continue to output old access_token values. In this case, the backend of the Official Accounts Platform will ensure that both new and old access_token values are available within five minutes, so that third-party services are smoothly transitioned.

  3. The validity of access_token may be adjusted in the future. Therefore, the central control server not only needs to actively update access_token on schedule, but also provides an API for passive update of access_token. In this way, when learning that access_token is expired in a call, the service server may trigger the update procedure for access_token.

Both Official Accounts and Mini Programs can use AppID and AppSecret to call this API to get the access_token. AppID and AppSecret can be obtained in Weixin Official Accounts Platform > Development > Basic Settings (A developer account in a normal status is required). Before calling the API, you need to log in to the Weixin Official Accounts Platform, and go to Development > Basic Settings to add the server IP address to the IP whitelist; otherwise it will not be called successfully. An IP whitelist is not required for Mini Programs.

API Request Format

HTTP request method: GET
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

Parameters

Parameter Required Description
grant_type Yes Enter client_credential to get access_token
appid Yes Unique credential of third-party users
secret Yes The AppSecret. It is the key of the unique credential of third-party users.

Response Description

For a successful request, Weixin returns the following JSON packet to the Official Account:

{"access_token":"ACCESS_TOKEN","expires_in":7200}

Parameters

Parameter Description
access_token The obtained credential
expires_in The time when the credential expires (in sec)

When an error occurs, Weixin will return an error code and related information. An example of the JSON packet (for an invalid AppID error) is shown below:

{"errcode":40013,"errmsg":"invalid appid"}

Error codes

Error Code Description
-1 System is busy. Try again later.
0 Request successful
40001 Incorrect AppSecret or mismatched AppSecret. Check whether AppSecret is correct.
40002 Ensure that the value of grant_type field is client_credential.
40164 The IP address used to call this API is not in the whitelist. Set it in the API IP whitelist. (The IP address used by Mini Programs and Mini Games to call this API is not required to be in the whitelist)

Debug this API using webpage debugging tool