Back to Details

roblox-open-cloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

roblox-open-cloud

roblox-open-cloud

Open Cloud is the REST API surface for Roblox resources. It lets you build command-line tools, web apps, CI/CD pipelines, scheduled jobs, and external automation that read and write the same resources your live game servers use, without running a game server.
Cross-reference:
  • roblox-datastores/SKILL.md: in-engine DataStore API; Open Cloud Data Stores is the external counterpart.
  • roblox-gamepasses/SKILL.md: game passes, developer products, and subscriptions also have Open Cloud management endpoints.
  • roblox-networking/SKILL.md: for in-experience HTTP via 
    HttpService
    and the security model around outbound requests.
  • roblox-core/SKILL.md: services, 
    HttpService
    , script contexts.
Open Cloud 是 Roblox 资源的 REST API 接口层。它让你构建命令行工具、Web 应用、CI/CD 管道、定时任务和外部自动化，读取和写入与在线游戏服务器相同的资源，而无需运行游戏服务器。
交叉参考：
  • roblox-datastores/SKILL.md：引擎内 DataStore API；Open Cloud Data Stores 是对应的外部接口。
  • roblox-gamepasses/SKILL.md：游戏通行证、开发者产品和订阅也具有 Open Cloud 管理端点。
  • roblox-networking/SKILL.md：了解通过 
    HttpService
    进行体验内 HTTP 调用，以及出站请求相关的安全模型。
  • roblox-core/SKILL.md：服务、
    HttpService
    、脚本上下文。

Authentication

认证

Three auth models, in order of preference:
三种认证模型，按推荐程度排序如下：

1. API keys (recommended for most automation)

1. API 密钥（大多数自动化任务的推荐方式）

All Open Cloud APIs accept an 
x-api-key
header containing an API key string. Create keys on the Creator Dashboard → API Keys page.
  • A key's access is determined by the permissions of the user who owns it. It can reach any resource that user can, including their personal experiences and any group-owned experiences where they have the right role.
  • Some scopes can be restricted to specific experiences; not all.
  • Best practices (from the official docs):
    • Create separate keys per application to isolate blast radius.
    • Select the minimum permissions needed; restrict scope to specific experiences where possible.
    • Use IP restrictions (CIDR notation). But not when calling from Roblox game servers (Roblox server IPs aren't known/predictable).
    • Set expiration dates for short-term keys; avoid them for long-term use without a rotation process.
    • Never store keys in source control, scripts, or public channels. Use a secrets manager; in Roblox places use a Secrets Store.
    • For group-owned resources, create a dedicated alternate account with only the target group access and generate the key there. Don't use your personal account's key for group automation.
所有 Open Cloud API 都接受包含 API 密钥字符串的 
x-api-key
请求头。可在 Creator Dashboard → API Keys 页面创建密钥。
  • 密钥的访问权限由密钥所有者的权限决定。它可以访问该用户有权访问的任何资源，包括其个人体验，以及用户拥有相应角色的群组所属体验。
  • 部分 scope 可以限制到特定体验；并非所有 scope 都支持此限制。
  • 最佳实践（来自官方文档）：
    • 为每个应用创建单独的密钥，以隔离影响范围。
    • 仅选择所需的最低权限；尽可能将 scope 限制到特定体验。
    • 使用 IP 限制（CIDR 表示法）。但从 Roblox 游戏服务器调用时不要使用此限制，因为 Roblox 服务器 IP 未知且无法预测。
    • 为短期密钥设置过期日期；如果没有轮换流程，应避免将其用于长期用途。
    • 绝不将密钥存储在源代码、脚本或公开渠道中。请使用 secrets manager；在 Roblox Place 中使用 Secrets Store。
    • 对于群组所属资源，创建一个仅具有目标群组访问权限的专用备用账号，并在该账号下生成密钥。群组自动化不要使用个人账号的密钥。

2. OAuth 2.0 (for apps acting on behalf of other users)

2. OAuth 2.0（用于代表其他用户操作的 app）

Use OAuth 2.0 when your app needs to act on behalf of a Roblox user who isn't you (e.g. a third-party tool a creator logs into). See https://create.roblox.com/docs/cloud/auth/oauth2-overview. Has stronger stability guarantees and regular updates.
当你的 app 需要代表某个并非你的 Roblox 用户进行操作时，使用 OAuth 2.0，例如用户登录的第三方工具。参见 https://create.roblox.com/docs/cloud/auth/oauth2-overview。OAuth 2.0 具有更强的稳定性保证，并会定期更新。

3. legacy cookie auth (avoid)

3. 旧版 Cookie 认证（应避免使用）

Legacy APIs use cookie-based auth, can break without notice, and have minimal stability guarantees. Not recommended for production. Only use for one-off internal tooling where breakage is acceptable.
旧版 API 使用基于 Cookie 的认证，可能在无通知的情况下失效，且稳定性保证极少。不推荐用于生产环境。 仅当可以接受意外中断时，才将其用于一次性内部工具。

API key lifecycle

API 密钥生命周期

API keys have these statuses (from the official docs):
StatusReasonResolution
ActiveNo issues.N/A
DisabledYou toggled Enable Key off.Toggle it back on.
ExpiredExpiration date passed.Remove or set a new expiration.
Auto-ExpiredUnused or unmodified for 60 days (even without a set expiration).Disable then re-enable, or update any property.
RevokedGroup key: the generating account lost group access.Regenerate the key.
ModeratedA Roblox admin changed the key secret for security.Regenerate.
User ModeratedThe generating account is under moderation.Resolve the moderation.
The 60-day auto-expiry is the most common surprise: keys you set up and forget will silently stop working. Either use them regularly or build a rotation/reminder process.
API 密钥具有以下状态（来自官方文档）：
状态原因处理方式
Active未发现问题。不适用
Disabled你关闭了 Enable Key。重新启用它。
Expired过期日期已过。删除密钥或设置新的过期日期。
Auto-Expired60 天内未使用或未作任何修改（即使未设置过期日期）。先禁用再重新启用，或更新任意属性。
Revoked群组密钥：生成密钥的账号已失去群组访问权限。重新生成密钥。
ModeratedRoblox 管理员出于安全原因更改了密钥内容。重新生成密钥。
User Moderated生成密钥的账号正受到审核。解决审核问题。
60 天自动过期是最常见的意外情况：创建后被遗忘的密钥会悄无声息地停止工作。要么定期使用这些密钥，要么建立轮换或提醒流程。

Introspect endpoint

Introspect 端点

POST https://apis.roblox.com/api-keys/v1/introspect
verifies whether a key is usable from the caller's IP and whether the key/user is moderated. Useful for debugging "why is my key failing":
bash
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{"apiKey": "your-api-key"}'
Returns the key name, authorized user, scopes (with 
userId
/
groupId
/
universeId
/
universeDatastore
resource identifiers; 
*
means all resources of that type), 
enabled
, 
expired
, and 
expirationTimeUtc
.
POST https://apis.roblox.com/api-keys/v1/introspect
用于验证密钥能否从调用方 IP 使用，以及密钥或其用户是否受到审核。它非常适合用于调试“密钥为何失效”：
bash
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{"apiKey": "your-api-key"}'
返回密钥名称、授权用户、scope（包含 
userId
/
groupId
/
universeId
/
universeDatastore
资源标识符；
*
表示该类型的全部资源）、
enabled
、
expired
和 
expirationTimeUtc
。

The endpoint map

端点映射

Base URL: 
https://apis.roblox.com/cloud/v2/...
(plus a few 
apis.roblox.com/<feature>/v1/...
legacy paths for assets). All v2 endpoints accept 
x-api-key
.
基础 URL：
https://apis.roblox.com/cloud/v2/...
（另外还有少量用于资产的 
apis.roblox.com/<feature>/v1/...
旧版路径）。所有 v2 端点都接受 
x-api-key
。

Data and memory stores (the most-used surface)

数据存储和内存存储（最常用的接口范围）

Data stores (
/cloud/v2/universes/{universe_id}/data-stores/...
):
  • ListDataStores
    , 
    SnapshotDataStores
    (daily snapshot trigger).
  • ListDataStoreEntries
    , 
    CreateDataStoreEntry
    , 
    GetDataStoreEntry
    , 
    UpdateDataStoreEntry
    , 
    IncrementDataStoreEntry
    , 
    DeleteDataStoreEntry
    .
  • ListDataStoreEntryRevisions
    (version history per entry).
  • Scoped variants under 
    /data-stores/{data_store_id}/scopes/{scope}/entries/...
    .
  • Rate limits (v2): share the experience Data Store request budgets with in-engine APIs (read/write/list/remove scale with concurrent users). See error codes & limits and rate-limit external callers (fixed spacing or leaky bucket). Do not assume Open Cloud has a separate unlimited pool.
  • Legacy v1 (
    /datastores/v1/
    , 
    /ordered-data-stores/v1/
    ): after July 29, 2026 the fixed non-scaling tables on the throttling guide apply only to those legacy paths.
Memory stores (
/cloud/v2/universes/{universe_id}/memory-stores/...
):
  • Sorted maps: 
    ListMemoryStoreSortedMapItems
    , 
    CreateMemoryStoreSortedMapItem
    , 
    GetMemoryStoreSortedMapItem
    , 
    UpdateMemoryStoreSortedMapItem
    , 
    DeleteMemoryStoreSortedMapItem
    .
  • Queues: 
    CreateMemoryStoreQueueItem
    , 
    ReadMemoryStoreQueueItems
    , 
    DiscardMemoryStoreQueueItems
    .
  • FlushMemoryStore
    (requires 
    universe.memory-store:flush
    ).
Ordered data stores (
/cloud/v2/universes/{universe_id}/ordered-data-stores/...
):
  • ListOrderedDataStoreEntries
    , 
    CreateOrderedDataStoreEntry
    , 
    GetOrderedDataStoreEntry
    , 
    UpdateOrderedDataStoreEntry
    , 
    IncrementOrderedDataStoreEntry
    , 
    DeleteOrderedDataStoreEntry
    .
  • Same shared experience budget model as standard Data Stores v2 (see error-codes page).
Data Stores（
/cloud/v2/universes/{universe_id}/data-stores/...
）：
  • ListDataStores
    、
    SnapshotDataStores
    （触发每日快照）。
  • ListDataStoreEntries
    、
    CreateDataStoreEntry
    、
    GetDataStoreEntry
    、
    UpdateDataStoreEntry
    、
    IncrementDataStoreEntry
    、
    DeleteDataStoreEntry
    。
  • ListDataStoreEntryRevisions
    （每个条目的版本历史）。
  • 作用域变体位于 
    /data-stores/{data_store_id}/scopes/{scope}/entries/...
    。
  • 速率限制（v2）： 与引擎内 API 共用体验的 Data Store 请求预算（读、写、列出和删除额度会随并发用户数扩展）。参见错误代码与限制，并对外部调用方实施速率限制（固定间隔或漏桶算法）。不要假设 Open Cloud 拥有独立且不受限制的请求池。
  • 旧版 v1（
    /datastores/v1/
    、
    /ordered-data-stores/v1/
    ）：自 2026 年 7 月 29 日起，节流指南中的固定且不扩展的表仅适用于这些旧版路径。
Memory Stores（
/cloud/v2/universes/{universe_id}/memory-stores/...
）：
  • Sorted Map：
    ListMemoryStoreSortedMapItems
    、
    CreateMemoryStoreSortedMapItem
    、
    GetMemoryStoreSortedMapItem
    、
    UpdateMemoryStoreSortedMapItem
    、
    DeleteMemoryStoreSortedMapItem
    。
  • Queue：
    CreateMemoryStoreQueueItem
    、
    ReadMemoryStoreQueueItems
    、
    DiscardMemoryStoreQueueItems
    。
  • FlushMemoryStore
    （需要 
    universe.memory-store:flush
    ）。
Ordered Data Stores（
/cloud/v2/universes/{universe_id}/ordered-data-stores/...
）：
  • ListOrderedDataStoreEntries
    、
    CreateOrderedDataStoreEntry
    、
    GetOrderedDataStoreEntry
    、
    UpdateOrderedDataStoreEntry
    、
    IncrementOrderedDataStoreEntry
    、
    DeleteOrderedDataStoreEntry
    。
  • 与标准 Data Stores v2 使用相同的共享体验预算模型（参见错误代码页面）。

Universes and places

Universes 和 Places

  • GetUniverse
    , 
    UpdateUniverse
    .
  • PublishUniverseMessage
    (publish a message to all servers of a universe; external counterpart to 
    MessagingService
    ).
  • RestartUniverseServers
    (restart all live servers of a universe).
  • GetPlace
    , 
    UpdatePlace
    (publish a place version; the CI/CD primitive).
  • GetInstance
    , 
    UpdateInstance
    .
  • GetUniverse
    、
    UpdateUniverse
    。
  • PublishUniverseMessage
    （向 Universe 中的所有服务器发布消息；是 
    MessagingService
    的外部对应接口）。
  • RestartUniverseServers
    （重启 Universe 中的所有在线服务器）。
  • GetPlace
    、
    UpdatePlace
    （发布 Place 版本；CI/CD 的核心操作）。
  • GetInstance
    、
    UpdateInstance
    。

Assets

Assets

  • GetAsset
    , 
    ListAssetVersions
    , 
    GetAssetVersion
    (v1 path: 
    apis.roblox.com/assets/v1/assets/{assetId}
    ).
  • Asset upload (images, audio, models) via the assets API. Useful for batch-importing content.
  • GetAsset
    、
    ListAssetVersions
    、
    GetAssetVersion
    （v1 路径：
    apis.roblox.com/assets/v1/assets/{assetId}
    ）。
  • 通过 assets API 上传 Asset（图片、音频、模型）。适用于批量导入内容。

Users and inventories

用户和 Inventory

  • GetUser
    , 
    GenerateUserThumbnail
    .
  • ListInventoryItems
    .
  • GetUser
    、
    GenerateUserThumbnail
    。
  • ListInventoryItems
    。

Groups

群组

  • GetGroup
    , 
    ListGroupMemberships
    , 
    UpdateGroupMembership
    , 
    ListGroupRoles
    , 
    GetGroupRole
    , 
    ListGroupJoinRequests
    , 
    AcceptGroupJoinRequest
    , 
    DeclineGroupJoinRequest
    , 
    GetGroupShout
    .
  • GetGroup
    、
    ListGroupMemberships
    、
    UpdateGroupMembership
    、
    ListGroupRoles
    、
    GetGroupRole
    、
    ListGroupJoinRequests
    、
    AcceptGroupJoinRequest
    、
    DeclineGroupJoinRequest
    、
    GetGroupShout
    。

Monetization (cross-ref roblox-gamepasses)

变现（交叉参考 roblox-gamepasses）

  • Game passes: 
    CreateGamePass
    , 
    UpdateGamePass
    , 
    GetGamePassConfig
    , 
    ListGamePassConfigsByUniverse
    .
  • Developer products: 
    CreateDeveloperProduct
    , 
    UpdateDeveloperProduct
    , 
    GetDeveloperProductConfig
    , 
    ListDeveloperProductConfigsByUniverse
    .
  • Subscriptions: managed via subscription endpoints; webhook events for 
    cancelled
    /
    purchased
    /
    refunded
    /
    renewed
    .
  • 游戏通行证：
    CreateGamePass
    、
    UpdateGamePass
    、
    GetGamePassConfig
    、
    ListGamePassConfigsByUniverse
    。
  • 开发者产品：
    CreateDeveloperProduct
    、
    UpdateDeveloperProduct
    、
    GetDeveloperProductConfig
    、
    ListDeveloperProductConfigsByUniverse
    。
  • 订阅：通过订阅端点管理；
    cancelled
    /
    purchased
    /
    refunded
    /
    renewed
    对应 Webhook 事件。

Moderation and bans

审核和封禁

  • ListUserRestrictions
    , 
    GetUserRestriction
    , 
    UpdateUserRestriction
    (place- and universe-scoped), 
    ListUserRestrictionLogs
    .
  • ListUserRestrictions
    、
    GetUserRestriction
    、
    UpdateUserRestriction
    （Place 级和 Universe 级）、
    ListUserRestrictionLogs
    。

Luau execution

Luau 执行

  • CreateLuauExecutionSessionTask
    (run Luau against a universe/place from outside the engine; treat as privileged).
  • CreateLuauExecutionSessionTask
    （从引擎外部针对 Universe 或 Place 运行 Luau；应视为高权限操作）。

Notifications and configs

通知和配置

  • CreateUserNotification
    (send a notification to a user from outside the experience).
  • Configs (CreatorConfigs): 
    GetConfigRepositoryValues
    , draft/publish/revision flow for live configuration.
  • CreateUserNotification
    （从体验外 向用户发送通知）。
  • Configs（CreatorConfigs）：
    GetConfigRepositoryValues
    、线上配置的草稿/发布/修订流程。

Creator store

Creator Store

  • CreateCreatorStoreProduct
    , 
    GetCreatorStoreProduct
    , 
    UpdateCreatorStoreProduct
    , 
    CreatorStoreAssetsSearch
    .
See https://create.roblox.com/docs/en-us/cloud for the full, current list (new endpoints are added regularly).
  • CreateCreatorStoreProduct
    、
    GetCreatorStoreProduct
    、
    UpdateCreatorStoreProduct
    、
    CreatorStoreAssetsSearch
    。
有关完整且最新的端点列表，请参见 https://create.roblox.com/docs/en-us/cloud（系统会定期新增端点）。

Calling Open Cloud from in-experience (
HttpService
)

在体验内调用 Open Cloud（
HttpService
）

A subset of Open Cloud endpoints is callable from inside a live game server via 
HttpService
. This is how you do things like update group memberships or kick users from external triggers without leaving the experience.
Requirements:
  • Enable Allow HTTP Requests in Experience Settings.
  • The API key must be stored as a 
    Secret
    via the Secrets Store. Retrieve it with 
    HttpService:GetSecret("APIKey")
    . Never hardcode the key in a script.
  • Only the 
    x-api-key
    and 
    content-type
    headers are allowed.
  • The 
    x-api-key
    value must be a 
    Secret
    datatype, not a string.
  • The 
    ..
    string is not allowed in URL path parameters (so data stores/entries containing 
    ..
    are inaccessible from 
    HttpService
    ).
  • Only HTTPS; no ports below 1024 except 80/443; port 1194 blocked.
Rate limits (per game server):
  • 2500 Open Cloud requests per minute per server. Exceeding stalls request methods for ~30 seconds and 
    pcall
    may fail with "Number of Open Cloud requests exceeded limit."
  • Open Cloud requests do not count against the separate 500-req/min general HTTP limit.
  • Each endpoint also has a per-key-owner limit enforced regardless of where calls originate.
Example: update a group membership from an experience.
lua
--!strict
local HttpService = game:GetService("HttpService")

local function updateGroupMembership(groupId: string, membershipId: string, roleId: string)
    local response
    local ok, err = pcall(function()
        response = HttpService:RequestAsync({
            Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
            Method = "PATCH",
            Headers = {
                ["Content-Type"] = "application/json",
                ["x-api-key"] = HttpService:GetSecret("APIKey"), -- Secret, not string
            },
            Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
        })
    end)
    if not ok then
        warn("HTTP request failed:", err)
        return false
    end
    if response.Success then
        print("Updated:", response.StatusCode, response.StatusMessage)
        return true
    end
    warn("Error:", response.StatusCode, response.StatusMessage)
    return false
end
Best practices: pcall everything; retry safe reads by default, but retry mutations only with endpoint-specific idempotency semantics. On 429, honor 
retry-after
, then 
x-ratelimit-reset
, before bounded exponential backoff. Always retain the last response/error and do not sleep after the final attempt. Aggregate into bulk endpoints where possible; rely on HTTP/2 (automatic, but send lowercase header names). The Observability Dashboard (Creator Hub → Monitoring) shows request count and response time for your 
HttpService
calls.
部分 Open Cloud 端点可以从在线游戏服务器内部通过 
HttpService
调用。你可以利用它在不离开体验环境的情况下，更新群组成员关系或根据外部触发条件移除用户。
要求：
  • 在 Experience Settings 中启用 Allow HTTP Requests。
  • API 密钥必须通过 Secrets Store 存储为 
    Secret
    。使用 
    HttpService:GetSecret("APIKey")
    获取它。切勿在脚本中硬编码密钥。
  • 只允许使用 
    x-api-key
    和 
    content-type
    请求头。
  • x-api-key
    的值必须是 
    Secret
    数据类型，不能是字符串。
  • URL 路径参数中不允许出现 
    ..
    字符串，因此包含 
    ..
    的数据存储或条目无法通过 
    HttpService
    访问。
  • 仅允许使用 HTTPS；除 80/443 外，不允许使用低于 1024 的端口；端口 1194 被阻止。
速率限制（每个游戏服务器）：
  • 每个服务器每分钟最多发出 2500 个 Open Cloud 请求。超出限制后，请求方法会停滞约 30 秒，且 
    pcall
    可能因“Number of Open Cloud requests exceeded limit.”而失败。
  • Open Cloud 请求不计入单独的每分钟 500 个通用 HTTP 请求限制。
  • 每个端点还会对密钥所有者实施独立限制，无论调用来自何处。
示例：从体验内更新群组成员关系。
lua
--!strict
local HttpService = game:GetService("HttpService")

local function updateGroupMembership(groupId: string, membershipId: string, roleId: string)
    local response
    local ok, err = pcall(function()
        response = HttpService:RequestAsync({
            Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
            Method = "PATCH",
            Headers = {
                ["Content-Type"] = "application/json",
                ["x-api-key"] = HttpService:GetSecret("APIKey"), -- Secret, not string
            },
            Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
        })
    end)
    if not ok then
        warn("HTTP request failed:", err)
        return false
    end
    if response.Success then
        print("Updated:", response.StatusCode, response.StatusMessage)
        return true
    end
    warn("Error:", response.StatusCode, response.StatusMessage)
    return false
end
**最佳实践：**所有调用都使用 
pcall
包裹；默认可以安全重试读取操作，但仅在端点具有特定幂等语义时重试修改操作。遇到 429 时，先遵循 
retry-after
，再遵循 
x-ratelimit-reset
，最后采用有上限的指数退避。始终保留最后一次响应或错误，并且最后一次尝试后不要继续休眠。尽可能将操作聚合到批量端点中；使用 HTTP/2（自动启用，但请发送小写形式的标头名称）。Observability Dashboard（Creator Hub → Monitoring）会显示 
HttpService
调用的请求数量和响应时间。

Webhooks

Webhook

Open Cloud emits webhooks for certain events, including subscription events (
cancelled
, 
purchased
, 
refunded
, 
renewed
). Set up a webhook endpoint in your app, register it via the Cloud API, and Roblox will POST event payloads to it. This is the real-time path for subscription analytics without polling 
GetUserSubscriptionPaymentHistoryAsync
. See https://create.roblox.com/docs/en-us/cloud/webhooks/webhook-notifications.
Open Cloud 会为特定事件发送 Webhook，其中包括订阅事件（
cancelled
、
purchased
、
refunded
、
renewed
）。在 app 中设置 Webhook 端点，并通过 Cloud API 注册它，随后 Roblox 会将事件负载 POST 到该端点。对于订阅分析而言，这是无需轮询 
GetUserSubscriptionPaymentHistoryAsync
即可获取实时数据的路径。参见 https://create.roblox.com/docs/en-us/cloud/webhooks/webhook-notifications。

Decision tree: in-engine vs Open Cloud

决策树：引擎内还是 Open Cloud

NeedUse
Normal player data read/write during a live serverIn-engine 
DataStoreService
External bulk migration, cleanup, RTBF deletionOpen Cloud Data Stores
Scheduled daily snapshot before a risky publishOpen Cloud 
SnapshotDataStores
Restart all servers after a config changeOpen Cloud 
RestartUniverseServers
Publish a place from CIOpen Cloud 
UpdatePlace
Upload many assets programmaticallyOpen Cloud Assets
Update a group role from in-experience
HttpService
+ Open Cloud 
UpdateGroupMembership
Send a notification to a user outside the experienceOpen Cloud 
CreateUserNotification
Real-time subscription event analyticsOpen Cloud webhooks
Normal monetization prompts/grants in-experienceIn-engine 
MarketplaceService
Manage game pass/dev product config externallyOpen Cloud game passes / developer products
需求使用方式
在线服务器运行期间读取或写入普通玩家数据引擎内 
DataStoreService
外部批量迁移、清理和 RTBF 删除Open Cloud Data Stores
在高风险发布前执行定时每日快照Open Cloud 
SnapshotDataStores
配置变更后重启所有服务器Open Cloud 
RestartUniverseServers
从 CI 发布 PlaceOpen Cloud 
UpdatePlace
以编程方式批量上传 AssetOpen Cloud Assets
从体验内更新群组角色
HttpService
+ Open Cloud 
UpdateGroupMembership
向体验外的用户发送通知Open Cloud 
CreateUserNotification
实时分析订阅事件Open Cloud Webhook
体验内的常规变现提示和发放引擎内 
MarketplaceService
从外部管理游戏通行证或开发者产品配置Open Cloud 游戏通行证/开发者产品

Security checklist

安全检查清单

  • Keys stored in a secrets manager or Secrets Store, never in source/scripts.
  • Minimum-permission scopes; experience-restricted where possible.
  • IP restrictions for non-Roblox-server callers.
  • Expiration dates on short-term keys; rotation process for long-term.
  • Dedicated automation account for group resources (not your personal account).
  • No 
    ..
    in data store keys you need to reach from 
    HttpService
    .
  • pcall every call; retry reads safely and require explicit idempotency before mutation retries.
  • x-api-key
    passed as 
    Secret
    from 
    HttpService
    , not string.
  • Audit key usage via the introspect endpoint and the Observability Dashboard.
  • Disable/delete unused keys (they auto-expire after 60 days anyway, but don't rely on that as your only cleanup).
  • Treat 
    CreateLuauExecutionSessionTask
    as privileged: it runs Luau against your universe.
  • 密钥存储在 secrets manager 或 Secrets Store 中，绝不存储在源代码或脚本中。
  • 使用最低权限 scope；尽可能限制到特定体验。
  • 对非 Roblox 服务器调用方使用 IP 限制。
  • 为短期密钥设置过期日期；为长期密钥建立轮换流程。
  • 为群组资源使用专用自动化账号，而不是个人账号。
  • 需要通过 
    HttpService
    访问的数据存储键中不包含 
    ..
    。
  • 每次调用都使用 
    pcall
    包裹；安全重试读取操作，并在重试修改操作前明确确认其幂等性。
  • 通过 
    HttpService
    将 
    x-api-key
    作为 
    Secret
    传递，而不是字符串。
  • 通过 introspect 端点和 Observability Dashboard 审核密钥使用情况。
  • 禁用或删除未使用的密钥（它们无论如何都会在 60 天后自动过期，但不要仅依赖此机制进行清理）。
  • 将 
    CreateLuauExecutionSessionTask
    视为高权限操作：它会针对你的 Universe 运行 Luau。

Common mistakes

常见错误

  • Using legacy cookie-auth APIs for production (they break without notice).
  • Storing API keys in scripts or source control.
  • Using a personal account's key for group automation (compromises all your resources if the key leaks).
  • Hitting the 2500-req/min 
    HttpService
    Open Cloud limit by not batching.
  • Running bulk Open Cloud v2 Data Store jobs without a client-side rate limiter (shared experience budget → live servers throttle).
  • Expecting 
    ..
    in data store keys to work from 
    HttpService
    (it doesn't).
  • Forgetting the 60-day auto-expiry and having automation silently break.
  • Using Open Cloud for things the in-engine API already does (unnecessary external dependency and latency).
  • 在生产环境中使用旧版 Cookie 认证 API（它们可能在无通知的情况下失效）。
  • 将 API 密钥存储在脚本或源代码管理中。
  • 使用个人账号的密钥执行群组自动化（一旦密钥泄露，所有资源都会受到影响）。
  • 未进行批处理，触发 
    HttpService
    每分钟 2500 个 Open Cloud 请求的限制。
  • 运行批量 Open Cloud v2 Data Store 任务时未使用客户端速率限制器（共享体验预算会导致在线服务器被限流）。
  • 期望包含 
    ..
    的数据存储键能够通过 
    HttpService
    使用（实际上无法使用）。
  • 忘记 60 天自动过期机制，导致自动化悄无声息地中断。
  • 对引擎内 API 已能完成的操作使用 Open Cloud（只会增加不必要的外部依赖和延迟）。

How to proceed

操作步骤

  1. Identify whether the task is in-engine or external. If external, Open Cloud.
  2. Create an API key with the minimum scopes for the task. If group-owned, use a dedicated account.
  3. Store the key in a Secrets Store if calling from 
    HttpService
    ; otherwise in your secrets manager.
  4. Test with the introspect endpoint and a single GET.
  5. Build the workflow with pcall, header-aware rate limiting, and method/endpoint-aware retries. For bulk, prefer batch endpoints.
  6. Set up webhooks for events you want in real time (subscriptions).
  7. Monitor via the Observability Dashboard; rotate/replace keys before they auto-expire.
  1. 确定任务属于引擎内还是外部。如果在外部执行，则使用 Open Cloud。
  2. 创建具有任务所需最低 scope 的 API 密钥。如果资源属于群组，请使用专用账号。
  3. 如果从 
    HttpService
    调用，则将密钥存入 Secrets Store；否则存入你的 secrets manager。
  4. 使用 introspect 端点和单个 GET 请求进行测试。
  5. 构建工作流时加入 
    pcall
    、感知标头的速率限制，以及感知方法和端点的重试逻辑。对于批量任务，优先使用批量端点。
  6. 为需要实时获取的事件设置 Webhook，例如订阅事件。
  7. 通过 Observability Dashboard 进行监控；在密钥自动过期前完成轮换或替换。

Sources

来源

<!-- catalog:references:start -->
<!-- catalog:references:start -->

Reference index

引用索引

  • auth-and-keys.md: Configure API keys, OAuth, scopes, or key rotation.
  • calling-from-in-experience.md: Call supported Open Cloud endpoints through HttpService and handle retries.
<!-- catalog:references:end -->
  • auth-and-keys.md：配置 API 密钥、OAuth、scope 或密钥轮换。
  • calling-from-in-experience.md：通过 HttpService 调用受支持的 Open Cloud 端点并处理重试。
<!-- catalog:references:end -->