管理 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 场所中，使用 Secrets Store。
不要通过公共渠道共享 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 调用的认证。	N/A
已禁用	用户通过禁用启用密钥切换禁用了密钥。	启用启用密钥切换。
已过期	密钥的过期日期已过去。	要么移除，要么设置一个新的过期日期。
自动过期	用户在过去 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"
}