# 获取稳定版接口调用凭据

接口应在服务器端调用，详细说明参见服务端API。

# 接口说明

# 接口英文名

auth.getStableAccessToken

# 功能描述

• 获取小游戏全局后台接口调用凭据，有效期最长为7200s，开发者需要进行妥善保存；
• 有两种调用模式: 1. 普通模式，access_token 有效期内重复调用该接口不会更新 access_token，绝大部分场景下使用该模式；2. 强制刷新模式，会导致上次获取的 access_token 失效，并返回新的 access_token；
• 该接口调用频率限制为 1万次 每分钟，每天限制调用 50万 次；
• 与 getAccessToken 获取的调用凭证完全隔离，互不影响。该接口仅支持 POST JSON 形式的调用；
• 如使用云开发，可通过云调用免维护 access_token 调用；
• 如使用云托管，也可以通过微信令牌/开放接口服务免维护 access_token 调用；

# 调用方式

# HTTPS 调用

POST https://api.weixin.qq.com/cgi-bin/stable_token 

# 请求参数

# 返回参数

# 其他说明

# access_token 的存储与更新

• access_token 的存储空间至少要保留 512 个字符；
• 建议开发者仅在access_token 泄漏时使用强制刷新模式，该模式限制每天20次。考虑到数据安全，连续使用该模式时，请保证调用时间隔至少为30s，否则不会刷新；
• 在普通模式调用下，平台会提前5分钟更新access_token，即在有效期倒计时5分钟内发起调用会获取新的access_token。在新旧access_token交接之际，平台会保证在5分钟内，新旧access_token都可用，这保证了用户业务的平滑过渡； 根据此特性可知，任意时刻发起调用获取到的 access_token 有效期至少为 5 分钟，即expires_in >= 300；

# 最佳实践

• 在使用 getAccessToken 时，平台建议开发者使用中控服务来统一获取和刷新access_token。有此成熟方案的开发者依然可以复用方案并通过普通模式来调用本接口，另外请将发起接口调用的时机设置为上次获取到的access_token有效期倒计时5分钟之内即可；
• 根据以上特性，为减少其他开发者构建中控服务的开发成本，在普通调用模式下，平台建议开发者将每次获取的access_token 在本地建立中心化存储使用，无须考虑并行调用接口时会导致意外情况发生，仅须保证至少每5分钟发起一次调用并覆盖本地存储。同时，该方案也支持各业务独立部署使用，即无须中心化存储也可以保证服务正常运行；

# access_token 泄漏紧急处理

• 使用强制刷新模式以间隔30s发起两次调用可将已经泄漏的 access_token立即失效，同时正常的业务请求可能会返回错误码40001(access_token 过期)，请妥善使用该策略。其次，需要立即排查泄漏原因，加以修正，必要时可以考虑重置 appsecret；

# 调用示例

示例说明: 普通模式，获取当前有效调用凭证

# 请求数据示例

POST https://api.weixin.qq.com/cgi-bin/stable_token

请求示例1（不传递force_refresh，默认值为false）:

{
    "grant_type": "client_credential",
    "appid": "APPID",
    "secret": "APPSECRET"
}

请求示例2（设置force_refresh为false）:

{
    "grant_type": "client_credential",
    "appid": "APPID",
    "secret": "APPSECRET",
    "force_refresh": false
} 

# 返回数据示例

返回示例1:

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

返回示例2:

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

示例说明: 强制刷新模式，慎用，连续使用需要至少间隔30s

# 请求数据示例

POST https://api.weixin.qq.com/cgi-bin/stable_token

{
    "grant_type": "client_credential",
    "appid": "APPID",
    "secret": "APPSECRET",
    "force_refresh": true
} 

# 返回数据示例

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

# 错误码