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.

Authentication

Three auth models, in order of preference:

1. API keys (recommended for most automation)

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.

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

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.

3. legacy cookie auth (avoid)

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 key lifecycle

API keys have these statuses (from the official docs):

Status	Reason	Resolution
Active	No issues.	N/A
Disabled	You toggled Enable Key off.	Toggle it back on.
Expired	Expiration date passed.	Remove or set a new expiration.
Auto-Expired	Unused or unmodified for 60 days (even without a set expiration).	Disable then re-enable, or update any property.
Revoked	Group key: the generating account lost group access.	Regenerate the key.
Moderated	A Roblox admin changed the key secret for security.	Regenerate.
User Moderated	The 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.

Introspect endpoint

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":

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.

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.

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).

Universes and 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.

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.

Users and inventories

• GetUser, GenerateUserThumbnail.
• ListInventoryItems.

Groups

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

Monetization (cross-ref 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.

Moderation and bans

• ListUserRestrictions, GetUserRestriction, UpdateUserRestriction (place- and universe-scoped), ListUserRestrictionLogs.

Luau execution

• CreateLuauExecutionSessionTask (run Luau against a universe/place from outside the engine; treat as privileged).

Notifications and configs

• CreateUserNotification (send a notification to a user from outside the experience).
• Configs (CreatorConfigs): GetConfigRepositoryValues, draft/publish/revision flow for live configuration.

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).

Calling Open Cloud from in-experience (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.

--!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.

Webhooks

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.

The Transaction Refunded trigger is separate from the subscription events. It covers developer products, passes, private servers, and paid access, but not subscriptions. Its payload includes the buyer, product type and ID, the Robux amount (the product's original price, not what the buyer paid), the universe and place, the transaction or receipt ID, and the refund time. A refunded pass or avatar item is revoked by Roblox automatically; a refunded developer product's benefit exists only in your experience's code, so remove it from player data yourself when this notification arrives.

The October 2026 refund-trigger note is experimental guidance pending a second human review (critical tier). Verify the payload on a test purchase before relying on it.

Decision tree: in-engine vs Open Cloud

Need	Use
Normal player data read/write during a live server	In-engine DataStoreService
External bulk migration, cleanup, RTBF deletion	Open Cloud Data Stores
Scheduled daily snapshot before a risky publish	Open Cloud SnapshotDataStores
Restart all servers after a config change	Open Cloud RestartUniverseServers
Publish a place from CI	Open Cloud UpdatePlace
Upload many assets programmatically	Open Cloud Assets
Update a group role from in-experience	HttpService + Open Cloud UpdateGroupMembership
Send a notification to a user outside the experience	Open Cloud CreateUserNotification
Real-time subscription event analytics	Open Cloud webhooks
Normal monetization prompts/grants in-experience	In-engine MarketplaceService
Manage game pass/dev product config externally	Open Cloud game passes / developer products

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.

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).

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.

Sources

• https://create.roblox.com/docs/en-us/cloud
• https://create.roblox.com/docs/en-us/cloud/auth/api-keys
• https://create.roblox.com/docs/cloud/auth/oauth2-overview
• https://create.roblox.com/docs/en-us/cloud-services/http-service
• https://create.roblox.com/docs/en-us/cloud/reference/rate-limits
• https://create.roblox.com/docs/cloud-services/data-stores/error-codes-and-limits (Open Cloud v2 Data Store shared budgets)
• https://create.roblox.com/docs/cloud/guides/data-stores/throttling (legacy v1 Data Store limits)
• https://create.roblox.com/docs/en-us/cloud/webhooks/webhook-notifications
• https://create.roblox.com/docs/en-us/cloud-services/secrets

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.