Manage Multi-Tenant API Keys

Multi-Tenant “Enterprise” API keys provide a centralized way to programmatically access data across all managed tenants using a single API key. This capability is designed for Managed Security Service Providers (MSSPs) and large enterprises that manage complex ecosystems with dozens or even hundreds of tenants. By moving from a 1:1 relationship (one key per tenant) to a 1:N relationship (one key for many tenants), you can eliminate key sprawl and the massive operational overhead required to manually manage and rotate individual credentials per tenant.

Types of Enterprise API keys

There are 2 types of Multi-Tenant API keys available for Enterprise and MSSP environments:

• Enterprise admin key: Grants full administrative privileges to all current and future tenants managed by your primary account.
• Enterprise user key: Inherits and mimics the specific access permissions of the owner at the exact time of the API call.

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.

Generate an Enterprise Key

A Platform Administrator can generate an Enterprise admin key from the primary account, and any user can create an Enterprise user key from their primary account. You must copy and vault the key immediately, as it cannot be retrieved once you navigate away from the screen.

1. Log in to your primary (Partner/Enterprise) account.
2. From the left menu of the Rapid7 Command Platform Home page, click Administration.
3. Click API Key Management from the left menu of the Administration page.
4. Navigate to the Admin or User Keys tab, select the Enterprise sub-tab, and click the Generate New Key button.
5. When the panel appears, provide a descriptive name for the key.
6. Click Save/Generate. A window will display your new key.
7. Copy and store the key in a secure vault immediately.

Using Enterprise keys with Rapid7 APIs

To use an Enterprise API key, you must include a specific header to tell the Command Platform which tenant organization the request is for, and tailor your base API URL to match the region for the specified tenant organization.

• Authentication Header: Include your Enterprise key as the X-Api-Key header.

• Identifying Managed Organizations:

  • Use the Get Managed Organizations API  (with an Enterprise admin key) to retrieve a list of all Organization IDs managed by your account. This will include their associated region.
  • Alternatively, use the Get Managed Organizations by User API  (with an Enterprise admin key) to retrieve a list of all Organization IDs a specific user has access to.
  • You can then build a single integration that “loops” through these organization IDs and regions automatically.

• Organization Targeting:

  • Set the base API URL to ensure you are using the correct region for the target tenant organization.
  • Include the R7-Organization-Id header to specify the ID of the managed tenant for the request.

Revoking an Enterprise key

Revoking a key is permanent and immediately stops all automated processes using that credential.

1. Go to the Administration page, then the API Keys page.
2. Find the key in the Admin Keys (Enterprise) list.
3. Click the Delete (trash icon) button and confirm the revocation.

Automating Enterprise 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 unauthorized 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 Enterprise Admin API key, and your Platform Admin access is revoked within your primary account, you will no longer be able to manage the Enterprise Admin key. You’ll need to contact a platform administrator if you need to make changes to that key.