Managing API Keys

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 API Keys

You can create and configure API keys with granular permissions using the Creator Dashboard. 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 the group 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. For more information, see Group Resources.
  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.

  4. In the Access Permissions section, select an API from the Select API System menu, and click the Add API System button. Repeat for each API you need access to.

  5. Select an experience for the API to have access to.

  6. Add Experience Operations to your selected experience.

  7. In the Security section, explicitly set IP access to the key using CIDR notation, otherwise the you can't use the API key. 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 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 but significantly increases the risk for bad actors to steal your resources.
  8. (Optional): To add additional protection for your resources, set an explicit expiration date so your key automatically stops working after that date.

  9. Click the Save and Generate key button.

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

The API Key displays on the Credentials page on the Creator Dashboard. You can also use the API Key in external scripts and tools such as a GitHub action.

Group Resources

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

screeshot shows the creator 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. When you grant this permission to a member of your group, they have all the permissions that a group owner has for API keys, including the ability to create, view, edit, revoke, and audit all of the group's API keys.

You can also grant the Create group API keys permission to roles within your group, which allows members to only create and view keys that they own without being 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. To use these keys again, anyone who has the correct permissions must regenerate the keys.

CIDR Format

To further protect your resources, when creating an API key, specify IP addresses that can access 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

API keys initially have an active status, but they can become inactive over their lifetime. To learn why an API key has changed status(es) and how to return the API key back to an active status, see the following table:

Status Reason Resolution
Active No issues; the user can use the key to authenticate Open Cloud API calls. N/A
Disabled The user disabled the key by disabling the Enable Key toggle. Enable the Enable Key toggle.
Expired The key's expiration date has passed. Either remove or set a new expiration date.
Auto-Expired The user hasn't used or updated the key in the past 60 days. You can either disable then enable the Enable Key toggle, or you can update any of the key's properties, such as the name, description, or expiration date.
Revoked For group keys, the account that last generated the key no longer has sufficient access rights to manage the group's keys. Click the Regenerate Key to get a new secret.
Moderated A Roblox admin changed the key's secret for security reasons. Click the 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.