Create and Manage API Keys

This task is for users with the OC Developer role.

API keys allow you to send and receive data between software applications. You can generate API keys to connect your OpenCities site to other applications. For example, you can create a key to share a dynamically updating list of OC Lost Animal pages with a local animal shelter.

In OpenCities, you can generate and manage multiple keys per site and customize the permissions of each one.

Before December of 2024, developers could only create one API key per site, and you may have used it for multiple purposes. This old API key will be listed as legacy in API Management and will have access to all permissions. However, it will not be updated; for example, if you create a new content type, it will not automatically apply to the legacy API key. To maintain security, we recommend creating a new key for each use-case and deleting the legacy API key.

Create a New API Key

1. Use the site picker drop-down menu to select the site you want for this API key.
2. Go to More > API Management in the main menu.
3. In the API Keys tab, select Create Key.
4. Fill in the Key Details and select Create.
   
5. If you need to edit the key, select it from API Keys list, make your changes, and select Update.
6. To provide your API key to an external site or application, select the key and select Copy To Clipboard next to the API Key and App ID as necessary.

Key Details

The Key Details you can provide are:

• Key Name: Give your key a descriptive name to be used in the API Keys list.
• Contact Email: Provide an email address to be contacted when the key is deactivated, and so other developers know who to contact about the key.
• Deactivation Date: Set a date and time for when the key will automatically deactivate and stop working.
• Access: Check each permission, service, and endpoint you want for this API key, including specific content types for the key. Use these options to control what content and actions can be accessed via this API key. You must select at least one Page Type before selecting Create.

Once you have created the API key, you can edit any of the Key Details, such as the Contact Email and Access permissions. You can also retrieve your:

• API Key: only available after the key is created; select Copy To Clipboard to copy the string.
• App ID: only available after the key is created; select Copy To Clipboard to copy the string.

Manage Your API Keys

You can manage your keys in the API Keys list. This list will display each key created on the site and show you:

• Key Name: Select this name to edit the key.
• Key: The API key string, so you can copy it directly.
• Last used: The date of the last call made on this key.
• Status: Whether the key is Active or Inactive. API keys are marked Inactive when they are deactivated.

You can also use the cog wheel drop-down menu to:

• Edit: Update your Key Details
• Copy API Key to Clipboard: Copy the API key
• Copy App ID to Clipboard: Copy the App ID
• Deactivate: Deactivate the key so it no longer works. Use this options if you need to temporarily halt the key, before you Activate it again. You cannot update an Inactive API key.
• Delete: Permanently remove an API key from your site

Test Your API Key

In the Documentation section, you can test the methods and responses of any of the Active API keys on your site. You can use the drop-down menus to select the Api key and Host and then expand the permissions to Try it out and ensure your key is working as expected.

If the key does not work as expected, please edit your permissions and test it again.