应用密钥与凭证边界

App ID 可以随 SDK 公开；应用服务端密钥只能保存在你控制的游戏服务器。玩家 token、开发者控制台 token、管理员 token 和应用密钥互不替代。

创建和保存

在开发者控制台创建应用时，首次成功响应显示服务端密钥。立即保存到服务端密钥管理设施或本地受控环境。平台数据库仅保存密钥摘要，列表和详情不会重新显示明文；关闭弹窗后无法从应用列表找回。

创建或轮换采用请求幂等。同一请求 ID 重放返回原应用记录，但 serverKey 为 null、replayed 为 true；这是避免持久保存明文的设计，不是空密钥可用。若网络超时导致没收到首次密钥，重新发起一次轮换并保存新值，不重复创建同名应用。

游戏服务器使用

下面变量是说明性的配置名称，尖括号内容必须换成你自己应用的实际值：

$env:ACCOUNT_ORIGIN = 'http://127.0.0.1:18787'
$env:GAME_SERVER_KEY = '<从控制台保存的应用服务端密钥>'

游戏服务器在请求 /api/server/auth/exchange 时添加 X-API-Key。SDK 提交给游戏服务器的 JSON 只有 appId、code、codeVerifier；不要让浏览器直接持有密钥调用该接口，也不要把密钥填进 API 文档的共享截图或公共请求示例。

examples/game-server.mjs 以 GAME_SERVER_KEY 读取密钥，它不会加载 .env 文件。平台自身同名变量仅用于原星渊演示应用初始化；新开发者应用用控制台已保存的摘要验证，不需要平台管理员再替它设置环境变量。

轮换、扩端和停用

轮换后旧密钥立即失效，没有双密钥宽限窗口。提前准备游戏服务器配置更新，在维护窗口执行轮换并尽快更新所有实例；随后用新登录流程验证兑换成功、旧密钥兑换失败。已有玩家会话不会仅因正常密钥轮换被强制退出。

同一应用新增 H5、Android 或 iOS 平台会继承当前密钥摘要与控制台托管标记，不另发一把密钥；整款游戏重新待审，旧玩家会话与未兑换授权码被撤销。纯重命名保持应用状态与已有会话。原演示游戏若已在控制台轮换，重启不会再用旧平台环境变量覆盖该密钥。

应用/开发者被平台停用时，配置与新登录被拒绝，相关玩家会话和待兑换码被撤销。恢复审批不恢复已撤销 token。需要重新登录，而不是把旧 token 写回存储。

排错步骤

遇到 INVALID_GAME_KEY：检查请求头名称、应用归属、最近轮换和各游戏服务器实例的配置版本；不要输出密钥进行比对。遇到 APP_UNAVAILABLE：先检查审批/停用状态，换密钥不能绕过审批。遇到 INVALID_AUTH_CODE：生成新 PKCE 登录事务；密钥正确不代表旧授权码能重复兑换。

通过一次真实本地兑换验证后，继续查看 服务端起步 和 授权码兑换。

实现依据

packages/server/src/developer.ts 的应用创建、rotate-key、update；packages/server/src/platform.ts 的 keyManagedByDeveloper 处理与 app() 门禁；packages/server/src/app.ts 的 X-API-Key 校验。文档只描述控制台操作，不将内部管理路由加入公开 OpenAPI。