Manage Multi-Tenant API Keys

Multi-Tenant 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 Multi-Tenant API keys

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

• Multi-Tenant admin key: Grants full administrative privileges to all current and future tenants managed by your primary account.
• Multi-Tenant 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 a Multi-Tenant Key

A Platform Administrator can generate a Multi-Tenant admin key from the primary account, and any user can create a Multi-Tenant 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 Multi-Tenant 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 Multi-Tenant keys with Rapid7 APIs

To use a Multi-Tenant 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 Multi-Tenant key as the X-Api-Key header.

• Identifying Managed Organizations:

  • Use the Get Managed Organizations API  (with a Multi-Tenant 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 a Multi-Tenant 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 a Multi-Tenant 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 (Multi-Tenant) list.
3. Click the Delete button (trash icon) and confirm the revocation.

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