> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rapid7

> Connect Serval to the Rapid7 Insight platform so workflows can call InsightIDR, InsightAppSec, InsightConnect, and the Insight Account API on demand with a single platform API key.

## 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

| Capability               | Description                                                                                                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| InsightIDR requests      | Query and update detection and response data such as investigations and alerts.                                                                                                                                                                                              |
| InsightAppSec requests   | Work with application security data: apps, scans, scan configs, and vulnerabilities.                                                                                                                                                                                         |
| InsightConnect requests  | Call the orchestration and automation API.                                                                                                                                                                                                                                   |
| Insight Account requests | Manage platform-level resources such as your organization, users, and API keys.                                                                                                                                                                                              |
| InsightOps requests      | Call the log management API. Not currently functional through Serval - see Gotchas before relying on this.                                                                                                                                                                   |
| AI endpoint discovery    | When 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](https://docs.rapid7.com/insight/api-overview/) 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](https://docs.rapid7.com/insight/managing-platform-api-keys/).

<Steps>
  <Step title="Log in to the Rapid7 Insight platform">
    Sign in at [insight.rapid7.com](https://insight.rapid7.com/).
  </Step>

  <Step title="Open API key management">
    Click the gear icon in the top right corner, then click **API keys** in the dropdown menu.
  </Step>

  <Step title="Choose the key type">
    Select either **User API keys** or **Organization API keys**.
  </Step>

  <Step title="Generate the key">
    Click **Generate new key** and give it a descriptive name.
  </Step>

  <Step title="Copy the key immediately">
    Copy and save the API key right away - you will not be able to view it again.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  Rapid7 shows the API key only once, at creation time. If you lose it, you will need to generate a new key.
</Warning>

<Tip>
  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.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the Rapid7 connection form">
    In Serval, add a new Rapid7 connection.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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").
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

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

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The API Domain field rejects my value">
    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.
  </Accordion>

  <Accordion title="One Insight product works but another returns permission errors">
    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.
  </Accordion>

  <Accordion title="InsightOps requests are blocked">
    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.
  </Accordion>

  <Accordion title="Requests fail because the product prefix was repeated">
    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.
  </Accordion>

  <Accordion title="InsightIDR endpoints are not checked ahead of time">
    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.
  </Accordion>

  <Accordion title="Your region affects more than the web address">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Rapid7 integration.