PcoWSkbVqDnWTu_dm2ix

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

Creating an API Key for a Group

If you are a group owner, you can also create API keys to access your group resources.

To create an API key for a group:

  1. Navigate to the Credentials page on the Creator Dashboard.
  2. In Creator section of the left-hand navigation, select the dropdown arrow, then select the group you would like to access the API key.

An example image of the Group dropdown menu
  1. Create an API key.

For security purposes, the keys can only access resources that the group owns. For example, when you set permissions for an API key, you can only select experiences within your group.

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.

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