Using the Cloud Security (InsightCloudSec) API

To get started with using the Cloud Security (InsightCloudSec) API, you’ll need two things: an authentication method and access to the API documentation.

⚠️

Command Platform API keys are not supported for Cloud Security APIs

API keys generated in the Rapid7 Command Platform (Insight Platform), including User API Keys and Organization API Keys, are not compatible with the Cloud Security (InsightCloudSec) API.

To authenticate requests, create an API key in Cloud Security (InsightCloudSec). For instructions, see Creating an API key.

Establish an authentication method

There are currently two authentication methods when using the Cloud Security (InsightCloudSec) API:

API Key: An API Key is the preferred method of authentication. An active API key allows you to programmatically access InsightCloudSec by explicitly passing the key in the header of an API request. API Keys can be associated with all types of Cloud Security (InsightCloudSec) user accounts.
Auth Token: Auth tokens are generated by making a request to the /login endpoint with your username and password. The token can then be passed with subsequent requests. Tokens are available per session, so after you are logged out for whatever reason, you must generate a new token.

⚠️

Single Sign On (SSO) Users

If you use SSO to login to Cloud Security (InsightCloudSec), we advise that you interact with the API using an API key, especially if you only want to create workflow automation scripts or you are planning to utilize API-only flows.

Creating an API key

If you’re a Domain Admin or an Organization Admin, you can generate a personal API key from your user profile. Domain Admins and Organization Admins can also:

Generate a key from the API Keys tab in User Management (Settings > User Management > API Keys)
Create API-only users with the /v2/public/user/create_api_only_user endpoint
Generate an API key for a user ID with the /v2/public/apikey/create endpoint
- You can find a user’s ID using the /v2/public/users/list endpoint

ℹ️

Basic user?

Basic users can only generate API keys from their user profile if explicitly granted the API Key Generation Allowed permission. Domain and Organization Admins can grant this permission after a user has been created from the Update User window (Settings > User Management > Users > Action > Update User)

Once you have an API key, pass it in the Api-Key header with each request. The following Python example lists your cloud accounts:


import requests
import getpass
 
# API URL
base_url = input('Base URL (e.g., https://cloudsec.insight.rapid7.com): ')
api_key = getpass.getpass('Api-Key: ')
 
headers = {
    'Api-Key': api_key,
    'Accept': 'application/json'
}
 
response = requests.get(
    url=base_url + '/v2/public/clouds/list',
    headers=headers
)
 
print(response.status_code)
print(response.json())

Creating an auth token

⚠️

Rapid7 recommends API Key authentication

Rapid7 highly recommends using an API Key to authenticate instead of an auth token.

Endpoints are authenticated using an auth token when a user’s session ID is passed in the header of a request. You can obtain a session ID from the object returned upon successfully using the /v2/public/user/login endpoint with your Cloud Security (InsightCloudSec) username and password. Explore the following Python example for more information:


import requests
import getpass
 
# Collect credentials
base_url = input('Base URL (e.g., https://cloudsec.insight.rapid7.com): ')
username = input('Cloud Security (InsightCloudSec) username: ')
password = getpass.getpass('Password: ')
 
# Get auth token
response = requests.post(
    url=base_url + '/v2/public/user/login',
    json={'username': username, 'password': password},
    headers={'Accept': 'application/json'}
)
 
session_id = response.json().get('session_id')
print('x-auth-token:', session_id)

Accessing the API documentation

You can access the Cloud Security (InsightCloudSec) API documentation in two ways: through the Cloud Security (InsightCloudSec) interface or the public documentation site.

Release-specific API documentation

The release-specific API documentation is always up-to-date with the version of Cloud Security (InsightCloudSec) you’re currently using. You can access the release-specific API documentation in any of these ways:

Add /docs to the end of your Cloud Security (InsightCloudSec) URL in your browser. For example, if your Cloud Security URL is https://cloudsec.insight.rapid7.com, go to https://cloudsec.insight.rapid7.com/docs.
In the Command Platform, go to Administration > Cloud Security > Profile.
In Cloud Security, go to Administration > Profile > API Documentation.

ℹ️

DivvyCloud-based URLs

Some deployments may still use a DivvyCloud-based URL (for example, https://<customer-name>.customer.divvycloud.com). You can access the release-specific API documentation by appending /docs to that URL as well.

Public API documentation

The public API documentation is available on docs.rapid7.com . It does not require you to log in and includes improved details, expanded examples, and clearer usage information. However, because this documentation is updated on a separate release schedule, it might not always reflect the latest features or endpoints available in your environment. You can access the following API versions:

⚠️

Using prototype endpoints

You can use all endpoints, but endpoints under the prototype namespace may change and are not fully supported. If you have any questions or concerns, contact the Customer Support Portal .