Generate a new API key for Cloud9

You can generate a new API key from the Cloud9 Admin Portal.

Prerequisites

1. Required role: You must possess the Firm Admin role or a Custom Role with permissions to manage API keys.
2. Access security: The Cloud9 Admin Portal access itself requires 2FA authentication when enabled.
3. Required information: You must know the whitelisted IP addresses from which your API calls will originate and at least one Owner Email address.

Key generation steps

To generate a a new API key for Cloud9:

1. Log in to the Cloud9 Admin Portal. 
2. Select the API Keys tab in the left navigation pane.

The Manage your Cloud9 API Keys page has two sections: the Current Keys and Invalid Keys.

3. Select the Generate API Key button. 

4. Configure the API key parameters:

API: Select the Cloud9 API for which the key will be generated (for example, Management, Call Data, or Monitoring).

Environment: Select the environment for which the key will be generated. 

Whitelisted IP(s): Enter a comma-separated list of IP addresses (or IP ranges using CIDR notation) that will be permitted to access the Cloud9 API endpoint using this key. To ensure security, requests originating from IPs that are not on this list will be rejected.

Owner Email(s): Provide at least one owner email address. Key expiration notices will be sent to these email addresses 90, 30, and 7 days before expiry, as well as notifications when the key is generated or deleted.

Memo (optional): Add a note about the key's purpose.

Scope of Access (role-based access control): Select one of the predefined roles for the key.

• Admin: Full access to all endpoints and actions.
• Developer: Read and write access to all endpoints, but no delete rights.
• Read-Only: Only read access for all endpoints.

Based on the selected API and role, a table is displayed below in which you can set more granular permissions (Read, Create, Update, Delete). 

5. Select the Generate the Key and Secret button.

IMPORTANT: A pop-up window appears with both the public API Key and the private API Secret.This is the only time the API Secret is shown. Cloud9 cannot never retrieve this secret key. If the secret is lost, you must regenerate a new key pair. 

6. Copy the API Key the Secret from the pop-up window!
7. Close the modal. 

The new public key is listed under the Current Keys section and enabled.

Key security details

• Authentication method: The key and secret pair are used to compute an HMAC SHA512 signature that authenticates every request made to the API endpoints. Requests without a valid HMAC signature or from a non-whitelisted IP will be rejected (typically resulting in a 401 or 403 error).
• Expiration: API key/secret pairs expire after 1 year. New keys should be generated before expiration to maintain continuity.
• Modification: After creation, you can edit the whitelisted IPs and owner email(s) of API keys tab (Edit icon ).