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

Below the name and short description for each endpoint, there are three sections:

  • 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.
  • 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.

To the right of the request/responses section are the endpoint URL and method as well as request and response samples. 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 content.

  • If there are multiple samples, use the drop-down menu to select an available sample.
  • Click Copy to copy the sample
  • Click Expand All / Collapse All to expand or collapse objects within the sample

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.

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
# DivvyCloud 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": "DivvyCloud 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.

Below is a example of how you can use the API with an auth token using Python. This example lists all of the organizations inside InsightCloudSec.

Python example
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)