配置、AppSecret 与接口 token

配置业务服务器域名，并在应用后端取得、缓存和刷新接口 token。准备应用管理员权限、业务 HTTPS 域名，以及用于保存凭据的后端配置。

应用管理员管理 AppSecret；管理员和有开发权限的成员配置域名。微信兼容与平台原生接口采用各自鉴权方式，完整对照见下方 token 表。

服务器域名

在开发者中心打开应用，进入“配置与应用密钥”。请求域名和图片资源域名填写完整的 HTTPS Origin，例如 https://api.example.com；不接受 HTTP、IP 地址、localhost、通配符、路径、查询参数、重复值，也不能把同一 Origin 同时放入两组。

保存后检查页面显示的当前域名。出现并发修改冲突时刷新后重新编辑。宿主在启动、回到前台及周期刷新时读取配置，正常刷新周期为 60 秒；过期且无法更新时，新的网络及远程图片请求会失败。

业务请求由宿主按允许域名直连业务 HTTPS 地址，可以携带业务自己的登录态。平台和宿主凭据不放入业务请求。权限及最低宿主版本要求随包固定，变更时重新构建新版本。

预期结果： 保存的业务域名在宿主中可访问，未允许的目标被拒绝。

生成与保管 AppSecret

1. 使用应用管理员账号登录开发者中心，打开“配置与应用密钥”。draft 与 active 应用可设置服务器域名；disabled 应用也允许有权限人员修改域名及治理密钥以完成整改，运行仍关闭。
2. 点击“生成应用密钥”或“重置应用密钥”。
3. 输入当前账号密码完成重新认证。
4. 将一次性显示的 AppSecret 保存到应用后端的受保护配置中，然后关闭弹窗。

AppSecret 不得进入小程序源码、宿主制品、公开仓库、浏览器持久存储或日志。开发者中心仅在重置成功的当前弹窗显示值；关闭弹窗、离开页面或页面转为隐藏后会清除，不能再次读取。

每个应用只有一个当前代次。重置成功后旧密钥代次及绑定的接口 token 失效；旧 AppSecret 和旧接口 token 立即失效，没有宽限期。请求超时或页面关闭不代表操作一定失败，应先刷新并核对代次。若新值没有保存，只能再次重置。

获取与刷新接口 token

应用须为 draft 或 active，且当前 AppSecret 可用。草稿应用获取的接口 token 可用于兑换有效本地开发调试上下文签发的手机号 code，以及访问单独鉴权的MetaEco 余额支付接口。手机号从 code 记录校验调试会话；支付保留商户、签名和宿主付款会话校验，应用后端无需传入调试凭证。其他业务接口仍要求应用为 active；停用应用不能获取或使用 token。以下两个入口共享同一密钥代次的接口 token，获取参数、返回结构和后续传递方式按各自契约处理：

使用场景	获取入口	成功响应	后续鉴权
微信兼容手机号	GET /cgi-bin/token	顶层 access_token、expires_in	手机号接口 Query 的 access_token
平台原生会话、诊断、MetaEco 支付	POST /miniapp/v1/apps/{app_id}/access-token	code=miniapp_success，token 与到期字段在 data 内	Authorization: Bearer <接口 token>；资金写请求另需签名

微信兼容入口

应用后端使用 AppID 和 AppSecret 调用；普通接口白名单由平台为本应用确认：

curl --get "$PLATFORM_ORIGIN/cgi-bin/token" \
  --data-urlencode 'grant_type=client_credential' \
  --data-urlencode "appid=$APP_ID" \
  --data-urlencode "secret=$APP_SECRET"

成功正文直接提供 access_token 和 expires_in，没有平台 data 包装。失败可能仍为 HTTP 200：48001 表示本应用未进入普通接口白名单，40125 表示 AppSecret 不可用，-1 表示系统暂不可用。同时检查 HTTP 状态和正文，不能把错误正文当作 token。完整响应见获取小程序接口 token。

平台原生入口

应用后端以 HTTPS JSON 请求获取。不要把 AppSecret 放在 Authorization Header 中：

curl --request POST "$PLATFORM_ORIGIN/miniapp/v1/apps/$APP_ID/access-token" \
  --header 'Content-Type: application/json' \
  --data '{"app_secret":"<当前 AppSecret>","force_refresh":false}'

成功正文为 {"code":"miniapp_success","data":{"access_token":"<接口 token>","expires_in":7200,"expires_at":"<到期时间>"}}。这是结构示意，占位值由实际响应替换；失败使用平台 error 结构和相应 HTTP 状态。完整字段见获取接口调用 token。

缓存与刷新

接口 token 以 mat_ 开头，最长有效期 2 小时。默认请求返回当前密钥代次内仍有效的同一 token，重复获取不会自动延长有效期；expires_in 表示本次返回时的剩余秒数，原生入口还返回 expires_at。应用后端应统一缓存、预留时钟和传输余量，并由一个刷新流程协调多实例更新。只有确定要立即替换 token 时才在原生入口传 force_refresh: true，该操作会吊销旧 token，所有使用它的实例都须更新。重新调用兼容入口也不会绕过应用白名单。

后续应用后端接口使用：

Authorization: Bearer <接口 token>

接口 token 只能保存在应用后端，不得返回给小程序 JS。收到接口 token 无效响应时，应用后端可用当前 AppSecret 重新获取一次；持续失败时检查应用状态、密钥代次和冻结状态，避免无界重试。

冻结、解冻与停用应用

冻结后当前 AppSecret 认证立即被拒绝，绑定的当前接口 token 同时吊销；密钥值和代次不变。解冻恢复 AppSecret 认证，但不会恢复已吊销 token，应用后端须重新获取。重置、冻结和解冻都绑定当前 generation；并发操作只有一个能成功，过期 generation 返回冲突。

授权管理员可对 disabled 应用查询、重置、冻结和解冻 AppSecret，但 disabled 状态仍阻止业务认证和接口 token 签发。恢复应用运行后，应用后端再使用当前可用 AppSecret 获取新 token。

重置或冻结 AppSecret 不会仅因密钥变化撤销既有平台会话。应用停用后旧平台会话不能继续使用，恢复流程也不会复活旧凭据。上述操作都不会替应用业务后端撤销自有业务登录态；应用仍须按自己的风控和退出规则管理业务会话。

无权限时请确认账号拥有目标应用授权。反馈问题只提供 App ID、密钥代次、操作时间和请求 ID，不提交 AppSecret、接口 token 或密码。登录接入见身份与登录。

常见失败

现象	处理
域名保存失败	使用完整 HTTPS Origin，去掉路径、Query 和片段，检查重复值
48001	本应用未进入普通接口白名单，联系平台确认开放范围
40125 或密钥认证失败	检查当前 AppSecret、冻结状态和应用状态
旧 token 失效	确认是否重置、冻结或强制刷新，更新后端缓存
重置成功后没保存新值	当前密钥无法再次读取，管理员重新重置并更新后端

下一步

按身份与登录建立业务登录态。需要手机号时使用微信兼容 token；需要余额支付时继续支付接入。