跳到主要内容

API key 管理

最后更新：2026 年 7 月 16 日

API key 是用于认证 PlayServ SDK 和 REST API 调用的凭据。每个 key 都限定在某个 Project、某种类型和某个 Environment 之内。

一个 Project 可以有多个 key —— 用于不同的接入方、不同的 Environment，或是轮换流程。按接入方分开使用 key，可以精确地吊销某一处的访问权限，而不牵连其他无关的服务。

key 的类型​

信息

PlayServ 有两种 key —— Server 和 Client。按这个 key 将在哪里运行来选择。

Server key 拥有完整的后端访问权限。请在你的 game server、后端服务和 CI 流水线中使用它。Server key 可以调用 PlayServ REST API 的任何 endpoint，包括那些会修改数据的。正因如此，Server key 必须严格保密，绝不能打进客户端 build，也不能随游戏一起分发。

Client key 的权限被限定在一小组操作上：发布 Event 和读取 Catalog。它们的设计就是可以安全地放进游戏 build 里。即使 Client key 被人从 build 中提取出来，损失也有限 —— 它无法修改服务端数据，也拿不到普通游戏客户端权限之外的任何东西。

Server keyClient key
权限任意 REST API endpoint，包括写操作发布 Event、读取 Catalog
用在哪里game server、后端服务、CI对外分发的游戏 build
能放进客户端 build 吗？不能 —— 绝不要分发可以，本就如此设计
一旦泄露该 Project 的后端被完全掌握影响范围有限
危险

绝不要把 Server key 打进客户端 build。从游戏二进制中提取出的 Server key，会让攻击者获得你 Project 后端的完整访问权限。凡是会到达 Player 手上的东西，都用 Client key。

注意

请把所有 API key 都当作敏感凭据。不要在工单、截图、聊天消息、Slack 讨论串或公开仓库中分享它们。

为什么一个 Project 会有多个 key​

同一个 Project 可以包含任意数量的 key。这在几种常见场景下很有用：

  • 后端服务和 CI 流水线各自持有自己的 Server key，这样任何一方都能独立轮换，互不影响。
  • 游戏客户端用 Client key，后端用 Server key。两者绝不应共用同一份凭据。
  • 轮换 key 时，有第二个 key 就可以先签发新凭据、更新服务，再吊销旧的 —— 避免停机。
  • 可以为外包人员、特定 build 或外部接入签发临时 key，用完即吊销。

把 key 分开并起好名字，Project 越长越大时，这张 key 表就越好管。

创建 key​

1

打开 Keys 页面

在 Project 侧边栏中打开 Keys。如果还没有任何 key，页面会显示一个空状态，带有 Create your first key 按钮，以及一个方便查阅的 Read the auth docs 链接。

API key 页面 —— 空状态

2

打开创建表单

点击 + Create key（或 Create your first key）打开创建表单。

创建 API key 的表单

3

填写信息并创建

  • Name —— 起一个能清楚说明这个 key 用在哪里的名字。例如：dev-server-backend、dev-client-unity-build、ci-deploy-key。日后想在表里认出某个 key，靠的就是这个描述性的名字。
  • Type —— 根据接入场景选择 Server 或 Client。不确定选哪个，请看上面的 key 的类型。
  • Environment —— 选择目标 Environment。目前可选 Dev。

点击 Create key。完整 token 只显示一次 —— 请立刻保存（见下面的 保存 token）。

保存 token​

创建之后，完整的 token 值会在 Save your token 对话框中恰好显示一次。

Save your token 对话框

请立刻复制 token，并存放到安全的地方 —— 密码管理器、secret 管理系统，或者 CI 系统中的环境变量。点击 I've saved it, close 关闭对话框。

注意

这是完整 token 唯一一次显示的机会。对话框一旦关闭，secret 就无法再取回，只能轮换。如果 token 在保存之前就丢了，你只能轮换这个 key 来拿到新的。

key 列表​

关闭对话框后，这个 key 会出现在 Keys 表中。一个同时拥有 Server key 和 Client key 的 Project 看起来是这样：

同时包含 Server key 与 Client key 的 API key 列表

表中显示：

  • Name —— 你在创建时指定的标签
  • Type · Env —— key 的类型（Server 或 Client）以及它所属的 Environment
  • Prefix —— key 开头的几个字符，便于在不暴露完整值的前提下辨认当前用的是哪个 secret
  • Key ID —— 这条记录的稳定标识符，与 secret 的值无关
  • Status —— 这个 key 上次被使用的时间；never 表示还从未使用过

key 很多的时候，可以用 Server、Client 和 Dev 这几个筛选标签缩小列表。

重命名 key​

要修改 key 的名字，点击表中对应的那一行。名称字段会就地变为可编辑 —— 输入新名字后按 Enter 保存。

在 key 表中就地重命名

备注

重命名不会影响 key 的 secret，也不影响它的认证能力 —— 只是更新表里的标签。

接入方式随时间变化时，用它把名字保持准确 —— 比如把 dev-server-sdk-key 改成 ci-deploy-server-key，因为它后来被挪去做 CI 流水线了。

轮换 secret​

当你怀疑当前 secret 已经泄露，或者按照常规的凭据轮换策略，就该轮换 key。轮换会替换 secret 的值，但保留这条 key 记录 —— key ID、名称、类型和 Environment 都保持不变。

1

打开轮换对话框

点击某个 key 所在的行，选择 Rotate secret。会弹出一个确认对话框。

轮换 secret 的确认对话框

2

确认并保存新 token

注意

轮换之后，旧的 secret 会立刻停止认证。任何还在用旧 secret 的服务都将连不上。请在轮换之前、或轮换后第一时间，把新 secret 更新到所有受影响的服务。

点击 Rotate secret 确认。新 token 会在同一个 Save your token 对话框中显示一次 —— 关闭之前请先复制。

轮换后的 Save your token 对话框

吊销 key​

吊销 key 会把它从 Project 中永久移除。当某个 key 不再需要、需要终止外包人员的访问权限，或者 key 已被攻破且仅靠轮换不足以解决时，就该这么做。

1

打开吊销对话框

点击某个 key 所在的行，选择 Revoke key。会弹出一个确认对话框。

吊销 key 的确认对话框

2

确认吊销

注意

吊销之后，这个 key 会立刻停止认证。任何正在使用它的服务都会失去访问权限。吊销前请确认这个 key 已经没人在用，或者做好在吊销后立刻更新受影响服务的准备。

点击 Revoke key 确认。在它被永久移除之前，你有 10 秒钟的时间通过 toast 通知或该 key 所在的行撤销这次操作。

最佳实践​

  • 起有描述性的名字。 半年后再来看这张表时，名字是你唯一能据以判断某个 key 用途的东西。
  • 一个接入方一个 key。 不要在互不相关的服务之间复用同一个 key。一旦某处被攻破，你会希望自己只吊销那一个 key 就够了。
  • 绝不要把 Server key 放进客户端 build。 从游戏二进制中提取出的 Server key，会让攻击者获得你 Project 后端的完整访问权限。
  • 怀疑泄露就轮换。 只要你有任何理由认为某个 secret 被不该看到的人看到了，立刻轮换。
  • 吊销闲置的 key。 不再使用的 key 是没必要承担的风险，要定期清理。

下一步​

标签：
最后于 更新