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
- You can find a user's ID using the
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
1import json2import requests3import getpass45requests.packages.urllib3.disable_warnings() # verify=False throws warnings otherwise67# Username & password8username = ''9password = ''1011# API URL12base_url = ''1314# Param validation15if not username:16username = input('InsightCloudSec username: ')17if not password:18password = getpass.getpass('Password: ')19else:20password = password2122if not base_url:23base_url = input('Base URL (EX: http://localhost:8001 or http://45.59.252.4:8001): ')2425headers = {26'Content-Type': 'text/plain',27'Accept': 'application/json'28}2930# Get auth token31def get_token():32data = {33'username': username,34'password': password35}36print(data)37response = requests.request(38method = 'POST',39url = base_url + '/v2/public/user/login',40json = data,41verify = False,42headers = headers43)44headers['x-auth-token'] = response.json().get('session_id')4546get_token()47print(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