PcoWSkbVqDnWTu_dm2ix
The Developer Hub is now deprecated and information on this page may no longer be accurate. To see our new and improved documentation, please click here. You can read more about the future of documentation here.

15 min

Open Cloud enables you to build applications and tools to access your Roblox resources through web APIs. There are several cases in which you may need to programmatically access your creations, including:

  • Browsing player data for customer support
  • Automating the commit, test, and publish workflow
  • Editing models and saving them to Roblox

While Open Cloud initially supports API key-based access to help automate your internal workflows, the ultimate goal is to improve your efficiency creating content on Roblox through an application ecosystem of tools and services.

API Access

Open Cloud authenticates and authorizes API access with the use of API keys. Authentication proves that your applications are who they say they are, similar to when you log into Roblox using your username and password. Authorization proves your application has the right to make certain requests.

Creating an API Key

The Creator Dashboard lets you create and configure API keys with granular permissions; for example, you can select an experience you own with its associated resources based on the APIs you want to use. The API key string allows the application to authenticate to Open Cloud on your behalf.

To create an API key:

  1. Navigate to the Credentials page on the Creator Dashboard.
    • If the API key is for a group, select it under the "Creator" dropdown on the top left. You must be the group owner or assigned to a role within the group that is granted the API key admin permission (see below)
  2. On the upper-right of the screen, click the Create API Key button.
  3. Enter a unique name for your API key. Use a name that helps you recall its purpose later, such as CICD_KEY, for continuous integration and deployment tooling access.
An example image of the New API Key section of the Credentials page with the Name field highlighted.
  1. In the Access Permissions section, select an API from the Select API System menu, and click Add API System for each API you need access to.
An example image of the Access Permissions section of the Credentials page with the Add API System button highlighted.
  1. Select an experience for the API to have access to.

    Warning: For security reasons, configure the least amount of APIs and permissions as required. For example, to automate the publishing workflow for an experience, select the Place Management API, the experience, and the Write permission. If the API key is leaked, bad actors are only able to write a new version to all places in the experience. They wouldn't be able to access any other experience or resource.
An example image of the Access Permissions section of the Credentials page with the Add Experience button highlighted.
  1. In the Security section, explicitly set IP access to the key using CIDR notation, otherwise the API key cannot be used. For more information, see CIDR Format.

    1. Recommended: Find the IP address of your local machine, and add it to the Accepted IP Addresses section. Add additional IP addresses as needed for those that need access.
    2. Not Recommended: If you don’t have a fixed IP, add 0.0.0.0/0 to the Accepted IP Addresses section to allow any IPs to use your API key. This makes API access easier for many developers, but significantly increases the risk for bad actors to steal your resources.

An example image of the Security section of the Credentials page with the Add IP Address button highlighted.
  1. Optional: To add additional protection for your resources, set an explicit expiration date so your key will automatically stop working after that date.

An example image of the Security section of the Credentials page with the Expiration date field highlighted.
  1. Click the Save and Generate key button.

An example image of the Security section of the Credentials page with the Save and Generate Key button highlighted.
  1. Copy and save the API key string to a secure location.

    Warning: The API key string is equivalent to the password of your application. Save it in a secure place (not a public repo of your code) and never share it with untrusted parties e.g. anyone outside of your development team.

An example image of the Security sections of the Credentials page with the Copy Key highlighted.

The API Key is now ready for use! Aside from publishing a place, you can also use an API Key in a GitHub action.

Group Resources

API keys can manage resources that are owned by groups instead of users. To manage API keys within the context of a group, select it in the “Creator” drop-down at the top-left:

An example image of the Group dropdown menu

An API key created for a group can only access resources that its creator also has access to within that group. For example, in order to create an API key that can publish a place file, the group member’s role must have the Create and edit group experiences permission turned on.

Granting Permissions

As a group owner, you can grant the Administer all group API keys permission to roles within your group. By assigning a member to such a role, you can allow them to have all the permissions that a group owner can do for API keys, including create, view, edit, revoke, and audit all of the group’s API keys.

Group owners can also grant the Create group API keys permission to roles within their group, which has a more limited scope: this allows members in this role to create and view keys that they own. They won’t be able to manage others’ keys.

Revoking Permissions

There are multiple ways a user may lose the ability to manage group API keys:

  • They are assigned to a different role which lacks the permission. This happens during a transfer of group ownership.
  • The permission is disabled on their currently assigned role.
  • They leave or are exiled from the group.
  • Their account is moderated by Roblox and cannot log into the creator dashboard.

In any of the above cases, API keys generated by that user are given the Revoked status (see statuses below). These keys must be regenerated to be used again.

CIDR Format

To further protect your resources, you must specify IP addresses that are allowed to use the API key with either normal IP addresses or using the CIDR notation. A CIDR IP address looks like a normal IP address except it ends with a slash and a decimal that represents how many bits of the IP address are significant for network routing:

  • Normal: 192.168.0.0
  • CIDR: 192.168.0.0/24

The former part is the IP address and the latter part is the netmask, counting the bits of 1s in binary format. In the example above, 24 means 255.255.255.0 (24 1s) and would allow all IPs between 192.168.0.0 and 192.168.0.255. This is particularly useful if you plan to run your applications on a server.

API Key Status

An API key starts off as active but can become inactive over its lifetime for various reasons. The statuses an API key has is described on the edit view, and each one is described below. A key can have multiple statuses, such as being both Disabled and Expired, so you may have to take one or more steps resolve all of a key's issues.
StatusReasonHow to Resolve
Active No issues; the key can be used to authenticate Open Cloud API calls. N/A, although you can remove this by switching "Enable Key" off.
Disabled The key was disabled by the user with the "Enable Key" switch. Switch "Enable Key" on.
Expired The key's expiration date has passed. Set a new expiration date or use "No Expiration".
Auto-Expired† The key has not been used or updated in the past 60 days. Update any of the key's properties such as the name, description, expiration date. Toggling the "Enable Key" switch off and on again also works.
Revoked For group keys, the account that last generated the key no longer has sufficient access rights to manage the group's keys. Click "Regenerate Key" to get a new secret.
Moderated The key's secret was last changed by a Roblox admin for security reasons. Click "Regenerate Key" to get a new secret.
User Moderated The account that last generated the key is under some moderation status. Resolve the moderation issue on the account.

†API keys that aren’t actively used will always automatically expire, even if the Expiration field is set to “No Expiration”. This reduces the risk of an old API key that was leaked from being unintentionally used by a bad actor. If you are no longer using an API key, you should manually disable or delete it.

Place Management API

The Place Management API fulfills the same functionality as Publish to Roblox in Studio. This API updates all existing places of an experience to a new version, making it useful to build a CI/CD pipeline.

Publishing Places

To publish all places of an experience:

  1. Create an API key that has at least the following permissions for the experience you want to publish:
    • Place Management API
    • Write
  2. Add the API Key in the x-api-key header of a POST request to the API. Here’s an example curl command that references an xml Roblox place file at “/home/placefiles/place1.rbxlx”:
    $ curl  --verbose --location --request POST 'https://apis.roblox.com/universes/v1/{universeId}/places/{placeId}/versions?versionType=Published' \
    --header 'x-api-key: ' \
    --header 'Content-Type: application/xml' \
    -d @/home/placefiles/place1.rbxlx
    {"versionNumber":9}

    For binary place files (rbxl) please use the following command:

    $ curl --verbose  --location --request POST 'https://apis.roblox.com/universes/v1/{universeId}/places/{placeId}/versions?versionType=Published' \
    --header 'x-api-key: ' \
    --header 'Content-Type: application/octet-stream' \
    --data-binary @/home/placefiles/place1.rbxl
    {"versionNumber":9}

    Note:

    • Only HTTPS requests are supported.
    • To get the universeId, go to https://www.roblox.com/develop, find the experience you want to upload, click the Gear button, and then click Configure experience. The universeId will appear in the URL. For example: https://www.roblox.com/universes/configure?id=123456#/#basicSettings
    • To get the placeId, follow the steps above, then go to the Places tab and click the place you want to use. The placeId will appear on the URL. For example: https://www.roblox.com/games/987654/My-place

  3. Verify the upload at https://www.roblox.com/places/{place-id}/update#. Replace {place-id} with the real placeId of the experience you want to publish.
Tags:
  • open cloud