Getting Started with the InsightAppSec API

Generating an Insight API Key

In order to interact with the API, you’ll need to generate an API key. There are two kinds of API keys: a User Key, and an Org Key.

• User Keys: All role are able to generate a user key. This key is associated with your account and will track all changes and actions that you make.
• Org Keys: Only platform admins can generate an Org key. This is a “super key” and can do everything in the API across all products.

While Platform Admins have access to both a User Key and an Org Key, Rapid7 Recommends that Platform admins use only the Org Key.

API key roles and permissions

When you generate an API key, the InsightAppSec API inherits your product role and allows you to complete specific actions based on those roles. Platform Admins have Org Keys and can complete all actions in the API.

Roles and privileges are constantly evolving along with the API. For the latest user privileges, refer to the "Permissions" table in the InsightAppSec API documentation.

See Managing API Keys for more information.

1. Generate an API Key

To interact with the Rapid7 InsightAppSec API, you'll need an API key. Below are the steps for generating a new API key.

1. Login to the Rapid7 Insight Platform.
2. Click the gear icon at the top right of the page
3. Select API Keys.
4. Select one of the following using the toggle:
   • New User Key. All roles are able to generate a user key. This key is associated with your account and will track all changes and actions that you make.
   • New Organization Key. Only platform admins can generate an organization key. This is a "super key" and can do everything in the API across all products.
5. Once generated, be sure to copy and securely store the key, as it cannot be accessed again later

As stated before, this API key will allow you to begin interacting with the Rapid7 InsightAppSec API. More specifically, the API key is used in authenticating to your instance of InsightAppSec and performing transactions within that context. The key will be passed as part of every API request via a single HTTP header: X-Api-Key.

2. Generate a spec file

Full documentation for the Rapid7 InsightAppSec API is available here: https://help.rapid7.com/insightappsec/en-us/api/v1/docs.html

When navigating the document, use the menu on the left hand side to select the InsightAppSec component you'd like more info on, and then further narrow that by selecting individual API operations. You can also search the API documentation by keyword.

Each individual operation section will contain details on URL path, API parameters, request body (if required), and response samples. All of these can be used to construct an API request and perform the associated operation in the context of InsightAppSec.

Note that the beginning of the API documentation guide also contains additional info on permissions, searching/filtering, API errors, and query parameters that can be used in API requests.

Using the OpenAPI/Swagger Specification

Along with the HTML generated documentation, an OpenAPI/Swagger spec is made available and can be used for auto generating API clients or for use in Postman. The spec can be downloaded from https://help.rapid7.com/insightappsec/en-us/api/v1/insightappsec-api-v1.json. Usage of this file in conjunction with a tool such as Postman can be key for better familiarizing with a new API.

3. Access the API Via Postman

Postman is an API client that provides a simple user interface to allow for API interaction. It can be used in conjunction with the InsightAppSec API spec file to automatically generate requests to perform API calls. The following steps can be used to import the spec file into Postman. This will automatically generate requests to perform API calls, and is extremely useful when initially getting familiar with a new API endpoint.

1. Open Postman.
2. Select Import and select Choose File and select the InsightAppSec spec file that was downloaded.
3. Select the new InsightAppSec API section that's available under Collections.

Under this newly imported InsightAppSec API Collection, you can see an entry listed for each component that exists in InsightAppSec. If you expand the options and select a specific operation, a pre-formatted request will appear on the right that contains the operation type, the URL path, the body (if needed), and any necessary headers.

3a. Test the API

Although this pre-formatted request does contain the majority of the required fields for making an API call, there are a couple fields that need to be updated. The following steps can be used to make a request in Postman, when utilizing the imported spec file.

1. Select an operation from the InsightAppSec Collection.
2. In the URL field, replace the {{baseurl}} with the correct value (https://[region].api.insight.rapid7.com/ias/v1).
3. Update any placeholder query parameters in the URL, such as index and sort. If you're uncertain of these parameters, you can remove them from the URL (including the ?).
4. Under the Headers tab add a new header, where the key is X-Api-Key and the value is your previously generated API key.
5. Update any placeholder values in the request Body (if any), denoted with text such as <string>.
6. Select the Send button to make the request.
7. Observe the response received. A status code in the 200 range will mean the request was successful. If it failed, the response may contain an error message denoting the reason.

Use these steps with any additional calls to better familiarize with the InsightAppSec API, while also keeping in mind that some are more sensitive than others (such as DELETE operations).