管理 API 密钥 | 文档 - Roblox 创作者中心

Open Cloud 使用 API 密钥进行身份验证和授权 API 访问，这使您能够为访问和利用游戏中的某些资源（例如数据存储和地点）添加细粒度的权限和安全控制。

所有 Open Cloud API 都要求您创建一个具有有效权限的 API 密钥，并在请求中包含 x-api-key 头，这允许应用程序代表您进行 Open Cloud 身份验证。

创建 API 密钥

以下文本中所有关于 API 密钥的引用均指用户拥有的密钥。

您可以创建和配置 API 密钥以访问您的资源。API 密钥的访问权限由拥有该密钥的用户的权限决定。这意味着它通常可以访问用户拥有权限的任何资源，包括他们的单独游戏和任何群组拥有的游戏，只要他们具有适当的角色。某些范围可以限制为特定游戏，但并非所有。

有关如何为管理群组资源创建 API 密钥的详细信息，请参见下面的为管理群组拥有的资源创建 API 密钥部分。

要创建 API 密钥：

在创作者仪表板中，转到 API 密钥页面。
点击创建 API 密钥按钮。
输入一个唯一的 API 密钥名称。使用一个可以帮助您回忆起目的的名称，例如 PLACE_PUBLISHING_KEY 用于将地点发布到您的游戏。
在访问权限部分，从选择 API 系统菜单中选择一个 API。如果您需要将多个 API 添加到密钥，请重复此步骤。
如果适用，选择您想要通过 API 密钥访问的游戏。

您可以选择禁用按体验限制。禁用后，您的 API 密钥可以访问您所有的用户拥有的游戏以及您具有适当权限的任何群组拥有的游戏，包括您将来创建的任何游戏。
从选择操作下拉菜单中，选择您希望为 API 密钥启用的操作。

API 参考中的大多数操作都包含所需的权限范围。例如，刷新内存存储操作需要 universe.memory-store:flush 权限。

有关所有范围及其支持的 API 的列表，请参见范围。
可选
在安全性部分，使用 CIDR 表示法明确限制对密钥的 IP 访问。您可以找到本地计算机的 IP 地址，并将其添加到接受的 IP 地址部分，以及需要访问的其他 IP 地址。如果您没有固定 IP，或者仅在本地环境中使用 API 密钥，您可以保持限制 IP 地址切换未选中，以允许任何 IP 使用您的 API 密钥。
可选
为您的密钥设置过期日期，以增加对资源的额外保护。
点击保存并生成密钥按钮。
将 API 密钥字符串复制并保存到安全位置，而不是您代码的公共存储库。
在创作者仪表板的 API 扩展页面上验证您的 API 密钥状态。

API 密钥字符串相当于您应用程序的密码。切勿与不可信的方分享，例如您开发团队以外的任何人。

为管理群组拥有的资源创建 API 密钥

API 密钥授予用户帐户拥有权限的所有资源的访问权限，包括群组外的个人游戏。如果您使用个人帐户的 API 密钥进行群组自动化，并且该密钥被泄露，您访问的其他资源也会面临风险。

为防止这种情况，我们强烈建议在专用的备用帐户上创建一个单独的 API 密钥，该帐户的访问权限严格限制在目标群组内。这个专用于自动化目的的新帐户应仅被授予对目标群组的访问权限，并授予其任务所需的最低权限。

为您的自动化创建一个新的专用 Roblox 帐户。
邀请新帐户加入您的群组。
为其分配最低权限所需的群组角色（例如，仅“创建和编辑群组体验”）。
登录新帐户，并按照上面的步骤创建 API 密钥。
使用生成的 API 密钥进行群组资源自动化。

管理 API 密钥的最佳实践

API 密钥是敏感凭据，应保持安全以防止未经授权访问您的数据。以下是管理 API 密钥的一些最佳实践。

为每个应用程序创建单独的密钥：为每个应用程序或用例创建单独的 API 密钥，以隔离访问并减少密钥被泄露时的影响。
选择所需的最低权限：在配置范围时，选择密钥预期使用所需的最低权限。对于那些允许您按游戏限制范围访问的范围，仅限于所需的特定游戏。
使用 IP 地址限制：限制 API 密钥访问特定 IP 地址或 CIDR 范围，以防止来自未知位置的未经授权使用。在 Roblox 地点中使用 API 密钥时，请勿使用 IP 地址限制，以确保您的密钥可以与 Roblox 服务器一起使用。
设置过期日期：对于短期使用情况，配置过期日期以在设定时间后自动禁用密钥，从而降低密钥被泄露的风险。对于长期使用情况，不建议设置过期日期，除非您有密钥轮换流程，因为当密钥过期时，您的自动化可能会意外失败。
为群组资源管理使用专用备用帐户：使用具有最低权限的专用帐户进行群组资源管理，如为管理群组拥有的资源创建 API 密钥部分所述。
安全存储 API 密钥：切勿将 API 密钥直接存储在源代码、版本控制系统或可能暴露的脚本中。使用秘密管理系统来存储和控制对密钥的访问。在 Roblox 地点中，使用秘密存储。
不要通过公共渠道分享 API 密钥：切勿通过公共通信渠道、论坛或社交媒体分享 API 密钥。仅通过安全的私人渠道与可信的团队成员分享密钥。限制与您分享密钥的人员，以最小化密钥被泄露时的影响范围。

CIDR 格式

为了进一步保护您的资源，在创建 API 密钥时，指定可以访问 API 密钥的 IP 地址，可以使用普通 IP 地址或 CIDR 表示法。CIDR IP 地址看起来像普通 IP 地址，只是以斜杠和一个小数结尾，表示 IP 地址中有多少位对网络路由是重要的：

普通: 192.168.0.0
CIDR: 192.168.0.0/24

前面的部分是 IP 地址，后面的部分是子网掩码，计算二进制格式中 1 的位数。在前面的示例中，24 表示 255.255.255.0（24 个 1），允许所有 IP 在 192.168.0.0 和 192.168.0.255 之间。理解 CIDR 格式特别有用，如果您计划在服务器上运行应用程序。

API 密钥状态

API 密钥最初具有活动状态，但在其生命周期内可能会变为非活动状态。要了解 API 密钥状态为何发生变化以及如何将 API 密钥恢复为活动状态，请参见以下表格。

如果您或您的群组在 60 天内未使用或更新 API 密钥，它将自动过期，即使没有设置过期日期。这降低了恶意行为者使用旧 API 密钥的风险。如果您不再使用 API 密钥，您应该手动禁用或删除它。

状态	原因	解决方案
活动	没有问题。用户可以使用该密钥进行 API 调用的身份验证。	不适用
已禁用	用户通过禁用启用密钥切换禁用了该密钥。	启用启用密钥切换。
已过期	密钥的过期日期已过。	要么移除，要么设置新的过期日期。
自动过期	用户在过去 60 天内未使用或更新该密钥。	您可以禁用然后启用启用密钥切换，或者您可以更新密钥的任何属性，例如名称、描述或过期日期。
已撤销	仅适用于群组密钥。生成密钥的帐户不再具有管理群组密钥的足够访问权限。	点击重新生成密钥以获取新的密钥。
已审核	出于安全原因，Roblox 管理员更改了密钥的秘密。	点击重新生成密钥以获取新的密钥。
用户审核	生成密钥的帐户正在接受 Roblox 的审核。	解决该帐户上的审核问题。

检查 API 密钥

POST api-keys/v1/introspect

检索有关 API 密钥的信息。验证密钥是否可以从请求者的 IP 地址使用，以及密钥或最后生成的用户是否被审核。

请求

(application/json)

键	值
apiKey	<api_key>

示例检查 API 密钥请求

curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

响应

每个范围对象中可能存在四个资源标识符：

userId
groupId
universeId
universeDatastore

userId 和 groupId 标识符仅与具有创建者目标的范围相关。universeDatastore 标识符仅与具有 universe-datastore 目标的范围相关。对于不支持资源选择的范围，将省略资源标识符。

资源标识符列表中的星号（*）表示该范围对所有该类型的资源具有权限。

示例检查 API 密钥响应

{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}