管理 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 金鑰直接存儲在您的源代碼、版本控制系統或可能暴露的腳本中。使用 secrets 管理系統存儲和控制對金鑰的訪問。在 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 金鑰狀態已更改以及如何將其恢復為活動狀態，請參見以下表格。

如果您或您的群組在 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"
}