Skip to main content

​
About Rapid7

Rapid7 is a security operations platform built around the Insight cloud, spanning detection and response (InsightIDR), application security (InsightAppSec), log management (InsightOps), and orchestration (InsightConnect). Serval connects to your regional Insight platform with a single API key, and that one connection fans out across the Insight product APIs plus the platform Account API. Everything happens on demand from workflows - there is nothing to install on the Rapid7 side. Authentication: API key (Insight platform key) - you provide your regional API Domain and an Insight platform API key, and Serval attaches the key to every request it makes on your behalf. Serval only ever sends the key to your regional Insight API host. Data sync: On-demand only. There is no background sync and no entity ingestion - Serval reads and writes Rapid7 data only when a workflow runs.

​
What the Rapid7 integration enables

CapabilityDescription
InsightIDR requestsQuery and update detection and response data such as investigations and alerts.
InsightAppSec requestsWork with application security data: apps, scans, scan configs, and vulnerabilities.
InsightConnect requestsCall the orchestration and automation API.
Insight Account requestsManage platform-level resources such as your organization, users, and API keys.
InsightOps requestsCall the log management API. Not currently functional through Serval - see Gotchas before relying on this.
AI endpoint discoveryWhen authoring workflows, Serval AI can discover the available endpoints for InsightAppSec, InsightOps, InsightConnect, and the Insight Account API. InsightIDR endpoints are not registered, so for InsightIDR the AI works from Rapid7’s public API documentation instead.
Anything the Rapid7 Insight platform APIs serve from your regional Insight API host can be accessed through Serval.

​
Get your credentials

You need a Rapid7 Insight platform API key - either a User API key or an Organization API key. The same key works across all Rapid7 Insight products in your region, but it inherits the product access of its owner, so the owner must have access to each Insight product you plan to use. Rapid7’s official guide is Managing platform API keys.
1

Log in to the Rapid7 Insight platform

Sign in at insight.rapid7.com.
2

Open API key management

Click the gear icon in the top right corner, then click API keys in the dropdown menu.
3

Choose the key type

Select either User API keys or Organization API keys.
4

Generate the key

Click Generate new key and give it a descriptive name.
5

Copy the key immediately

Copy and save the API key right away - you will not be able to view it again.
6

Note your Insight region

Your region determines your API domain. Common regions are us, us2, eu, ca, au, and ap - for example, the us region uses us.api.insight.rapid7.com.
Rapid7 shows the API key only once, at creation time. If you lose it, you will need to generate a new key.
Before generating the key, confirm its owner (the user, or the organization) has access to every Insight product you intend to call from Serval. The key carries exactly that owner’s product access.

​
Connect in Serval

1

Open the Rapid7 connection form

In Serval, add a new Rapid7 connection.
2

Enter the API Domain (required)

Enter only the bare regional host in lowercase, for example us.api.insight.rapid7.com - no https prefix, no path, no trailing slash. The form shows the helper text “Your Rapid7 API domain. Common regions: us, us2, eu, ca, au, ap. Example: us.api.insight.rapid7.com”. Anything else is rejected with “Must be a valid Rapid7 API domain (e.g., us.api.insight.rapid7.com, us2.api.insight.rapid7.com)”, and leaving it empty shows “This field is required”. The region prefix (for example “us”) becomes the connection’s name.
3

Enter the API Key (required)

Paste the Insight platform API key you copied from Rapid7 into the API Key password field (“Your Rapid7 API key”).
4

Submit the form

Click Submit. If installation fails, the form shows “Failed to install integration” with details appended when available. Serval stores both values and attaches the key to every Rapid7 request your workflows make.
When you open the connection’s settings later, the API Domain is shown in full, and the API key appears masked - bullet characters plus its last 4 characters. Saving an update with the API Key untouched or blank keeps the existing key, and the same applies to the API Domain, which is pre-filled with the current value - enter a value only for what you want to change. To rotate the key, click Replace (or the pencil icon, depending on the form) next to the masked value and paste the complete new key into the “Enter new value” box. Changing the API Domain also renames the connection, since the connection name follows the domain’s region prefix.

​
Verifying the connection

Serval does not test your credentials when you save them - a mistyped key, a revoked key, or a domain from the wrong region is accepted at save time - and this integration does not ship any built-in connection health checks. The first signal of a problem is a failed request when a workflow runs. To verify a new connection, run a workflow that makes a small read-only call - for example, an Insight Account request that lists your platform API keys.
  • A successful call proves the API Domain is reachable and the Insight platform accepts the key.
  • An authentication failure usually means the key is invalid or revoked, or the API Domain does not match the region where the key was created. Re-check the region prefix and, if needed, generate a fresh key in Rapid7 and update the connection.
A successful platform call proves the key is valid on the Insight platform - it does not prove the key’s owner has access to every Insight product. If platform calls succeed but one specific product returns permission errors, grant the key’s owner access to that product in Rapid7, or connect with a different key.

​
Gotchas and troubleshooting

The connect form accepts only a bare regional Insight host in lowercase. Values with an https prefix, a path after the host, a trailing slash, or stray spaces fail with “Must be a valid Rapid7 API domain (e.g., us.api.insight.rapid7.com, us2.api.insight.rapid7.com)”. Enter only the host, for example us.api.insight.rapid7.com.
A single platform key covers all Rapid7 products in your region, but it carries only the product access of the user or organization that owns it. If InsightAppSec calls succeed while InsightIDR returns a 403 (or vice versa), grant the key’s owner access to that product in Rapid7, or use a different key.
InsightOps lives on a separate log-management host - your region prefix followed by rest.logs.insight.rapid7.com - which is outside the hosts this integration is allowed to call. Serval only permits requests to your regional Insight API host, so InsightOps calls are rejected with “request URL is not allowed for service rapid7”. Treat InsightOps as not currently functional through this integration, even though its endpoints appear in the AI endpoint catalog.
InsightIDR, InsightAppSec, and Insight Account requests automatically add their product’s API prefix, so pass only the endpoint as shown after that prefix in Rapid7’s documentation - including the prefix again produces a doubled address and not-found errors. InsightConnect is the exception: its endpoints already include the product prefix, exactly as they appear in the endpoint catalog.
Unlike the other products, InsightIDR calls are freeform - Serval cannot validate the endpoint or method before the request runs, and Serval AI has no registered endpoint catalog for InsightIDR. Double-check InsightIDR endpoints against Rapid7’s InsightIDR API documentation if calls return not-found errors.
The region prefix of your API Domain (for example “us”) is used as the connection’s name and to derive the InsightOps log-management host. If your Rapid7 data lives in a different region, update the API Domain on the connection rather than working around it.
Need help? Contact support@serval.com for assistance with your Rapid7 integration.