API Documentation in InsightCloudSec

Welcome to the InsightCloudSec API documentation! Here you can learn how to interact with InsightCloudSec programmatically, enabling you to securely and simply automate your daily and/or most tedious workflows within the product.

  • All endpoints can be used but we caution the use of prototype-namespaced endpoints as documentation and support may vary.
  • Contact us through the Customer Support Portal if you have any questions or concerns.

InsightCloudSec has three API specification files. The endpoints are organized by an arbitrary versioning; there's no relevant correlation to the endpoints that are available in each file. You can access the API documentation via the links below:

API Documentation Tips

This API documentation is currently offered “as-is” and as such we want to provide the following recommendations:

  • If you are not familiar with our API or are working with these capabilities for the first time, we strongly recommend that you coordinate with your CSM or our support team. We make this recommendation because some use cases may require additional clarification and we are here to help. Working with us directly will ensure that you are able to use our API effectively for whatever goals you have.
  • As part of our commitment to a great customer experience, we are actively working on productizing our API. This includes outlining a hardened and repeatable standard for future endpoints and identifying common/high-impact use cases for verification and possibly revision/versioning.
  • Where possible, there are example requests and responses for the documented endpoints. See Working With Examples for more information.

If you have questions or concerns regarding the content here, or need support using our API reach out to us through the Customer Support Portal.

Using the API Docs

Each endpoint documentation is divided into two columns:

  • Left Column -- The left column contains a name and short description for the endpoint as well as information on:
    • Security -- the security scheme (or authentication method) available for the endpoint
    • Request -- list of request parameters organized by type (path, body, query, and header)
      • Most endpoints should have a description and type for each parameter as well as indicate if it's required for the request.
      • If the parameter is an object and contains additional nested parameters, click the parameter name to expose the additional parameters.
      • If the parameter has a default value, it will be displayed.
      • This section will not appear if the endpoint does not require a request body
    • Responses -- list of possible response schemas grouped by response code
      • Each endpoint should have at least one response code associated with it.
      • If there's a response schema associated with a particular response code, click the code to expand the schema.
  • Right Column -- The right column contains the endpoint URL and method, access to the "Try It" console, and request and response samples (where possible)
    • Each endpoint should have at least one request and response sample; we update samples as often as we are able but not every endpoint will have them.
    • If there are multiple samples, use the drop-down menu to select an available sample. The JSON code block associated with the sample (Request or Response) will update to match the selected sample.
    • Review Try It Console for more information on using the console

User Type Affects Access

Remember that only certain types of InsightCloudSec users have access to all endpoints documented. Verify your user type and the endpoint description before testing anything out. See Users, Groups, and Roles for more information on InsightCloudSec Identity Management.

Authentication

There are currently two methods of authenticating when using the InsightCloudSec API:

  • API Key -- The API Key is the preferred method of authentication. An active API key allows the user to programmatically access InsightCloudSec. API Keys can be associated with all types of InsightCloudSec user accounts, e.g., basic users, domain admins, etc.; you can even have an API-only user. See API Key Authentication for an example.
  • Auth Token -- Auth tokens are generated using the Login endpoint in conjunction with a user's username and password. The token can then be passed to subsequent endpoints to allow the user to programmatically access InsightCloudSec. Tokens are available per session, so after the user is logged out of the product for whatever reason, they must generate a new token. See Auth Token Authentication for an example. InsightCloudSec highly recommends using the API Key authentication method instead. As such, auth token authentication is not reflected in the API specification files.

Single Sign On (SSO) Users

If you're a customer that uses 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.

API Key Authentication

API Key Authentication

The InsightCloudSec API allows authentication via an API key that is explicitly passed in the header of a request. You can obtain an API key using the InsightCloudSec user interface or using the API with an existing user's ID. Any existing API key for a user will be deactivated upon generating a new API key. Below are examples of how you can use an API key with Python or Bash/cURL. This example lists all of the organizations inside InsightCloudSec.

Python example
python
1
# Script to list all organizations in InsightCloudSec using an API Key
2
3
import json
4
import requests
5
import getpass
6
7
requests.packages.urllib3.disable_warnings() # verify=False throws warnings otherwise
8
9
# API Key
10
api_key = ''
11
12
# API URL
13
base_url = ''
14
15
# Param validation
16
if not api_key:
17
key = getpass.getpass('API Key:')
18
else:
19
key = api_key
20
21
if not base_url:
22
base_url = input('Base URL (EX: http://localhost:8001 or http://45.59.252.4:8001): ')
23
24
headers = {
25
'Content-Type': 'application/json;charset=UTF-8',
26
'Accept': 'application/json',
27
'Api-Key': key
28
}
29
30
# Get Org info
31
def get_org():
32
data = {}
33
response = requests.get(
34
url = base_url + '/v2/prototype/domain/organizations/detail/get',
35
data = json.dumps(data),
36
verify = False,
37
headers = headers
38
)
39
return response.json()
40
41
# Execute functions
42
org_info = get_org()
43
print(org_info)
Bash/cURL example
curl
1
# API key to authenticate against the API
2
api_key=""
3
# InsightCloudSec URL EX: http://localhost:8001 or http://45.59.252.4:8001
4
base_url=""
5
# Get org info
6
org_url=`echo $base_url/v2/prototype/domain/organizations/detail/get`
7
curl \
8
--request GET \
9
--header "content-type: application/json" \
10
--header "accept-encoding: gzip" \
11
--header "Api-Key: $api_key" \
12
$org_url | gunzip | jq
13
14
# Example output:
15
# {
16
# "organizations": [
17
# {
18
# "status": "ok",
19
# "smtp_configured": true,
20
# "clouds": 63,
21
# "name": "InsightCloudSec Demo",
22
# "resource_id": "divvyorganization:1",
23
# "organization_id": 1,
24
# "bots": 17,
25
# "users": 21
26
# }
27
# ]
28
# }
Auth Token Authentication

Auth Token Authentication

Endpoints are authenticated via auth token when a user's session ID is passed in the header of a request. You can obtain this session ID from the object returned upon successfully using the Login endpoint with your InsightCloudSec username and password. If the session expires or the user logs out, the auth token will no longer be valid and the user will have to start a new session/generate a new session ID. InsightCloudSec highly recommends using the API Key authentication method instead. As such, auth token authentication is not reflected in the API specification files.

Included in this section is an example of how you can use the API with an auth token using Python. The example lists all of your organizations inside InsightCloudSec.

python
1
# Script to list all organizations in InsightCloudSec using an Auth Token
2
3
import json
4
import requests
5
import getpass
6
7
requests.packages.urllib3.disable_warnings() # verify=False throws warnings otherwise
8
9
# Username & password
10
username = ''
11
password = ''
12
13
# API URL
14
base_url = ''
15
16
# Param validation
17
if not username:
18
username = input('InsightCloudSec username: ')
19
20
if not password:
21
password = getpass.getpass('Password: ')
22
else:
23
password = password
24
25
if not base_url:
26
base_url = input('Base URL (EX: http://localhost:8001 or http://45.59.252.4:8001): ')
27
28
headers = {
29
'Content-Type': 'text/plain',
30
'Accept': 'application/json'
31
}
32
33
# Get auth token
34
def get_token():
35
data = {
36
'username': username,
37
'password': password
38
}
39
print(data)
40
response = requests.request(
41
method = 'POST',
42
url = base_url + '/v2/public/user/login',
43
json = data,
44
verify = False,
45
headers = headers
46
)
47
headers['x-auth-token'] = response.json().get('session_id')
48
49
# Get Org info
50
def get_org():
51
data = {}
52
response = requests.get(
53
url = base_url + '/v2/prototype/domain/organizations/detail/get',
54
data = json.dumps(data),
55
verify = False,
56
headers = headers
57
)
58
return response.json()
59
60
# Execute functions
61
get_token()
62
org_info = get_org()
63
print(org_info)

Try It Console

The InsightCloudSec API documentation provides access to the Try It Console, which allows you test endpoints against your specific InsightCloudSec instance. This is similar to other API Platform functionality, e.g., Postman, but exists side-by-side with our bespoke API documentation. Consult our Troubleshooting section or Getting Support if you encounter any issues while using the console.

To use the console:

  1. For a given endpoint, click TRY IT next to the endpoint method/URL to expand additional fields.
  2. Update the insightcloudsecUrl for your unique InsightCloudSec instance URL.
  3. For the Security section, input your Api-Key. Review Create API Key for more information.
  4. If the endpoint requires a request body, expand the Body section.
  5. Update the JSON code block using the Request documentation as a guide.
    • If the endpoint has associated samples, you can select one using the drop-down menu to automatically update the JSON code block. From here, you can edit the JSON as necessary.
  6. Click SEND. You'll automatically be switched to the RESPONSE tab, which will report any errors or successes.

Troubleshooting

CORS

CORS stands for Cross-origin resource sharing. It is a mechanism to allow resources to be accessed from another domain outside the domain from which the original resource was served, e.g., accessing your InsightCloudSec instance from the InsightCloudSec API Documentation Try It Console. For security reasons, SaaS-based deployments of InsightCloudSec do not currently support CORS. Because most browsers enforce CORS support, you will not be able to use the Try It Console. However, you can use an API platform, like Postman, which often do not enforce CORS. Contact Support for any comments, questions, or concerns.