Managing 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 two types of platform API keys:

  • User key - Represents a specific user in an organization. This type of key can only be created by a 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 your account role on the Command Platform. Find your account role in the following table to determine the type of key you can generate.

Role

Permissions

Platform administrator

You can generate, view, and manage API keys across all organizations.

Organization administrator

You can only generate, view, and manage API keys within your assigned organization.

User

You can only generate, view, and manage your own keys.

Generate an organization key

A platform or organization administrator can generate an organization key. You will need to copy the key immediately after you generate it. You will not be able to retrieve the key again after you navigate away from it.

To generate an organization key:

  1. From the left menu of the Rapid7 Command Platform Home page, click the Administration link.
  2. From the left menu of the Administration page, click API Keys.
  3. From the “API Keys” page, go to the “Organization Keys” tab and click the New Organization Key button.
  4. When the “Generate New Organization Key” panel appears, select an organization and provide a name for the key.
  5. Generate the key. A new window opens and displays the generated key.
  6. Copy the key. You will not be able to view it again after you close the window.

Generating a user key

Any user can generate a user key. A user key will inherit your account’s permissions, so anything you can do, your API key can do. Just remember that you need to copy the key immediately after you generate it. You will not be able to retrieve the key if you don't.

To generate a user key:

  1. From the left menu of the Rapid7 Command Platform Home page, click the Administration link.
  2. From the left menu of the Administration page, click API Keys.
  3. From the “API Keys” page, click the New User Key button.
  4. When the Generate New User Key panel appears, select an organization and provide a name for the key.
  5. Generate the key. A new window opens and displays the generated key.
  6. Copy the key. You will not be able to view it again after you close the window.

View API keys

To see a list of API keys that are viewable to you, log into your Rapid7 account and go to the “API Keys” page. The keys you can view depend on your role on the Command Platform.

The following table shows what each role should be able to view:

Role

Access

User

You’ll only be able to see your own API keys.

Organization admin

You’ll be able to see all of the API keys for your assigned organization.

Platform admin

You’ll be able to see all of the API keys across all organizations.

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 please make sure that you are not removing any keys that other users may need.

To revoke a key, log in to your Rapid7 account. Go to the Administration page, then the API Keys page, find the key you want to revoke, and click the Delete button. Confirm that you want to revoke the key.

Please note that deleting a user’s account does not delete organization keys that they’ve generated; it only removes their user keys. If you are deleting a user, and you also want to delete their organization keys, you will need to go to the “API Keys” page and manually remove their keys.

Automating 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 those to be deleted
  • Delete API keys that are no longer required

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