Using the InsightCloudSec API

To get started with using the InsightCloudSec API, you'll need two things: an authentication method and access to the API documentation.

Establish an authentication method

There are currently two authentication methods when using the 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 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 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)

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 InsightCloudSec username and password. Explore the following Python example for more information:

python
1
import json
2
import requests
3
import getpass
4


5
requests.packages.urllib3.disable_warnings() # verify=False throws warnings otherwise
6


7
# Username & password
8
username = ''
9
password = ''
10


11
# API URL
12
base_url = ''
13


14
# Param validation
15
if not username:
16
    username = input('InsightCloudSec username: ')
17
if not password:
18
    password = getpass.getpass('Password: ')
19
else:
20
    password = password
21


22
if not base_url:
23
    base_url = input('Base URL (EX: http://localhost:8001 or http://45.59.252.4:8001): ')
24


25
headers = {
26
    'Content-Type': 'text/plain',
27
    'Accept': 'application/json'
28
}
29


30
# Get auth token
31
def get_token():
32
    data = {
33
        'username': username,
34
        'password': password
35
    }
36
    print(data)
37
    response = requests.request(
38
        method = 'POST',
39
        url = base_url + '/v2/public/user/login',
40
        json = data,
41
        verify = False,
42
        headers = headers
43
    )
44
    headers['x-auth-token'] = response.json().get('session_id')
45


46
get_token()
47
print(headers)

Accessing the API documentation

API documentation availability

The API documentation is being slowly rolled out over several phases throughout May 2025. If your InsightCloudSec instance does not have the following links yet, check back soon!

The API documentation is accessible from InsightCloudSec. Because it is generated directly from the codebase, it's always up-to-date and in-sync with implementation. To see the documentation for yourself:

  • Click Help > API Documentation
  • Click User > Profile > API Documentation