Manage Platform API keys
An application programming interface key, or API key, allows you to set up access to the Command Platform. The API key is a unique identifier that serves as a form of authentication when you make calls to our API. In order to share data between your security applications and the Command Platform, you’ll need to generate an API key.
There are 2 types of platform API keys:
- User key - Represents a specific user in an organization. This type of key can be created by any user and inherits the permissions of the user. You cannot generate a user key for other users.
- Organization key - Represents an entire organization and is a super key. This type of key can do everything across all products. You can only generate an organization key if you are a platform or organization administrator.
API keys based on your Rapid7 account role
API key generation capabilities depend on whether you are a platform administrator within your account on the Command Platform.
| Key Type | Permissions |
|---|---|
| Organization key | Only platform administrators can generate, view, and manage organization keys. |
| User key | Any user can create a user key but only within organizations they have access to. User keys inherit the specific permissions of the owner at the time of use. Platform administrators can view and manage all user keys. Non-platform administrators can only view and manage their own user keys. |
Generate an organization key
A platform or organization administrator can generate an organization key.
Save your key immediately
Copy the key immediately after you generate it. You cannot retrieve it later.
To generate an organization key:
- From Command Home, go to Administration > Administrator API Keys.
- Select Generate New Organization Key.
- Select an organization and provide a name for the key.
- Select Save. A new window opens and displays the generated key.
- Copy the key. You won’t be able to view it again after you close the window.
- Select Done.
Generate a user key
Any user can generate a user key from API Key Management > User API Keys . A user key will inherit your account’s permissions, so anything you can do, your API key can do.
Save your key immediately
Copy the key immediately after you generate it. You cannot retrieve it later.
To generate a user key:
- From Command Home, go to Administration > User API Keys.
- Select Generate New User Key.
- Select an organization and provide a name for the key.
- Select Save. A new window opens and displays the generated key.
- Copy the key. You will not be able to view it again after you close the window.
- Select Done.
View API keys
The API keys you can view depend on your role on the Command Platform.
The following table shows what each role can view:
| Platform Admin Status | Access |
|---|---|
| Platform Admin | All of the API keys across all organizations |
| Standard User (Non-Platform Admin) | Only your API keys |
To view API keys:
- From Command Home, go to Administration.
- Select either User API Keys or Administrator API Keys.
Revoke an API key
Revoking an API key removes it from the Command Platform and makes it inaccessible to its owner. This action is permanent. You cannot revert this action, so make sure you’re not removing any keys that other users may need.
To revoke an API key:
- From Command Home, go to Administration and select either User API Keys or Administrator API Keys.
- Find the key you want to revoke and select the Delete icon.
- Select Revoke API Key.
Organization keys persist after user deletion
Deleting a user’s account doesn’t delete organization keys they’ve generated; it only removes their user keys. To delete their organization keys, go to the Admin Keys page and manually remove them.
Automate API key rotation
To help organizations better safeguard their data and systems, we recommend automating the rotation of Rapid7 API keys. Automated API key rotation significantly enhances security and compliance by reducing the risk of unauthorised access and potential breaches.
Regularly changing API keys limits the window of opportunity for malicious actors to exploit compromised keys, thereby protecting sensitive data and systems. Automating key rotation also reduces operational overhead and the risk of human error.
With the API Keys API you can:
- Get details of existing API keys
- Generate new API keys to replace deleted ones
- Delete API keys you no longer need
Changes to account permissions
Changes to your account’s permissions may affect your ability to view and manage API keys.
For example, if you created an organization API key, and your role changes to read/write only, you’ll no longer be able to manage the key. You’ll need to contact a platform administrator if you need to make changes to that key.