Open Cloud 使用 API 金鑰來驗證和授權 API 訪問，這使您能夠為訪問和利用您遊戲中的某些資源（例如數據存儲和地點）添加細粒度的權限和安全控制。
所有 Open Cloud API 都要求您創建一個具有有效權限的 API 金鑰，並在請求中包含 x-api-key 標頭，這使應用程序能夠代表您向 Open Cloud 進行身份驗證。
創建 API 金鑰
以下文本中所有對 API 金鑰的引用均指用戶擁有的金鑰。
您可以創建和配置 API 金鑰以訪問您的資源。API 金鑰的訪問權限由擁有該金鑰的用戶的權限決定。這意味著它通常可以訪問用戶擁有的任何資源，包括他們的個別遊戲和任何 群組擁有的 遊戲，只要他們擁有適當的角色。有些範圍可以限制在特定遊戲中，但並非所有。
有關如何創建 API 金鑰以管理群組資源的詳細信息，請參見下面的 為管理群組擁有的資源創建 API 金鑰 部分。
要創建 API 金鑰：
點擊 創建 API 金鑰 按鈕。
輸入您的 API 金鑰的唯一名稱。使用一個可以幫助您回憶起目的的名稱，例如 PLACE_PUBLISHING_KEY 用於將地點發佈到您的遊戲中。
在 訪問權限 部分，從 選擇 API 系統 菜單中選擇一個 API。如果您需要將多個 API 添加到金鑰，請重複此步驟。
如果適用，選擇您想要使用 API 金鑰訪問的遊戲。
您可以選擇禁用 按體驗限制。禁用後，您的 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 範圍，以防止來自未知位置的未經授權使用。在使用 API 金鑰於 Roblox 地點時，請勿使用 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 認證調用。 | N/A |
| 禁用 | 用戶通過禁用 啟用金鑰 切換禁用了該金鑰。 | 啟用 啟用金鑰 切換。 |
| 過期 | 金鑰的過期日期已過。 | 要麼刪除，要麼設置新的過期日期。 |
| 自動過期 | 用戶在過去 60 天內未使用或更新該金鑰。 | 您可以禁用然後啟用 啟用金鑰 切換，或者您可以更新金鑰的任何屬性，例如名稱、描述或過期日期。 |
| 撤銷 | 僅適用於群組金鑰。生成該金鑰的帳戶不再擁有管理群組金鑰的足夠訪問權限。 | 點擊 重新生成金鑰 以獲取新的密鑰。 |
| 已審核 | Roblox 管理員出於安全原因更改了金鑰的密鑰。 | 點擊 重新生成金鑰 以獲取新的密鑰。 |
| 用戶已審核 | 生成該金鑰的帳戶正在接受 Roblox 的審核。 | 解決該帳戶的審核問題。 |
內省 API 金鑰
POST api-keys/v1/introspect
檢索有關 API 金鑰的信息。驗證該金鑰是否可以從請求者的 IP 地址使用，以及該金鑰或最後生成的用戶是否受到審核。
請求
(application/json)
| 鍵 | 值 |
|---|---|
| apiKey | <api_key> |
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 目標的範圍相關。對於不支持資源選擇的範圍，將省略資源標識符。
資源標識符列表中的星號（*）表示該範圍對所有該類型的資源具有權限。
{
"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"
}