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:

• InsightCloudSec API v2
• InsightCloudSec API v3
• InsightCloudSec API v4

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
    • Review Authentication for more information
  • 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

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.

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)

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
# }

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.