Getting Started

This page will help you get started with the InsightCloudSec API

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, and feel free to use the "Suggest Edits" feature to provide any documentation feedback.

📘
Tips Around the API Documentation
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.
Also, where possible, there are example requests and responses for the documented endpoints. These are available in the "EXAMPLES" drop-down menus within the "REQUEST" and "RESPONSE" sections on the right-hand side of an endpoint page.
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 listed method, path, and short description for each endpoint, there is a list of parameters organized by type (path, body, query, and header). To the right of the parameters is the request and response examples.

📘
User Type Effects Access
Only certain types of users have access to all endpoints documented here. Verify your user type and the endpoint description before testing anything out.

Parameters

Each parameter will have a text field or drop-down menu (depending on the type of field) that you can interact with. Most endpoints should have a description and type for each parameter as well as indicate if it's required for the request (the field will be highlighted in red if it's required)
If the parameter has a default value, it will be displayed in inactive text or pre-selected (depending on the type of field)
If the endpoint has an example request associated with it (see Examples for more information), click the field to display example values that you can click to input automatically ("Use Example Value")

Working with Examples

This API documentation includes an example feature, which, when selected automatically fills all the fields on the left-hand side with example information. Users can copy-and-paste the request JSON into their API workflow as necessary.

Note: We updated examples as often as possible, but not every endpoint will have content.

Each endpoint has at least one request and response example. If the endpoint does not have a language-specific example, the request example will be auto-generated
If the request example is autogenerated:
- You may select a language to see the autogenerated example in the desired language
- Input your API key to update the request example with your API key; the browser will save this value so it will be available when you interact with other endpoints
- Within the URL, click the domain to open a text field where you can input and update the request example with your custom InsightCloudSec domain; the browser will save this value so it will be available when you interact with other endpoints
- Click the "Examples" drop-down menu in the upper right corner of the request box to display a list of pre-fabricated example requests. Select an example to update the parameter fields and request accordingly
- Editing parameters will affect the request example
Click one of the listed examples or the "Examples" drop-down menu in the upper right corner of the response box to display a list of pre-fabricated example responses. Select an example to display the response accordingly

Authentication

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

API Key: API Keys can be associated with all types of InsightCloudSec user accounts, e.g., basic users, domain admins, etc. An active API key allows the user to programmatically access InsightCloudSec. The API Key is the preferred method of authentication, and as such, is the only authentication type listed in the examples for each endpoint
Auth Token: Auth tokens are generated using the Login endpoint in conjunction with a user's username and password. This token can then be passed to subsequent endpoints to allow the user to programmatically access InsightCloudSec. This token is available per session, so when the user is logged out of the product for whatever reason, they must generate a new auth token.

Note: Only one of API Key or Auth Token is required. If both are provided, only the API Key will be used.

🚧
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 instead, especially if you only want to create workflow automation scripts or you are planning to utilize API-only flows.

API Key Authentication

Endpoints are authenticated via a user's API key when it 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). Note: any existing API key for a user will be deactivated upon generating a new API key.

Below is a sample of how you can use the API with an API key using Python or Bash/cURL. This example lists all of the organizations inside InsightCloudSec.

# Script to list all organizations in InsightCloudSec using an API Key

import json
import requests
import getpass

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

# API Key
api_key = ''

# API URL
base_url = ''

# Param validation
if not api_key:
    key = getpass.getpass('API Key:')
else:
    key = api_key

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

headers = {
    'Content-Type': 'application/json;charset=UTF-8',
    'Accept': 'application/json',
    'Api-Key': key
}

# Get Org info
def get_org():
    data = {}
    response = requests.get(
        url = base_url + '/v2/prototype/domain/organizations/detail/get',
        data = json.dumps(data),
        verify = False,
        headers = headers
    )
    return response.json()    

# Execute functions
org_info = get_org()
print(org_info)

# API key to authenticate against the API
api_key=""
# DivvyCloud URL EX: http://localhost:8001 or http://45.59.252.4:8001
base_url=""
# Get org info
org_url=`echo $base_url/v2/prototype/domain/organizations/detail/get`
curl \
--request GET \
--header "content-type: application/json" \
--header "accept-encoding: gzip" \
--header "Api-Key: $api_key" \
$org_url | gunzip | jq

# Sample output:
# {
#   "organizations": [
#     {
#       "status": "ok",
#       "smtp_configured": true,
#       "clouds": 63,
#       "name": "DivvyCloud Demo",
#       "resource_id": "divvyorganization:1",
#       "organization_id": 1,
#       "bots": 17,
#       "users": 21
#     }
#   ]
# }

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. Note: 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.

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

# Script to list all organizations in InsightCloudSec using an Auth Token

import json
import requests
import getpass

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

# Username & password
username = ''
password = ''

# API URL
base_url = ''

# Param validation
if not username:
    username = input('InsightCloudSec username: ')

if not password:
    password = getpass.getpass('Password: ')
else:
    password = password

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

headers = {
    'Content-Type': 'text/plain',
    'Accept': 'application/json'
}

# Get auth token
def get_token():
    data = {
        'username': username,
        'password': password
    }
    print(data)
    response = requests.request(
        method = 'POST',
        url = base_url + '/v2/public/user/login',
        json = data,
        verify = False,
        headers = headers
    )
    headers['x-auth-token'] = response.json().get('session_id')

# Get Org info
def get_org():
    data = {}
    response = requests.get(
        url = base_url + '/v2/prototype/domain/organizations/detail/get',
        data = json.dumps(data),
        verify = False,
        headers = headers
    )
    return response.json()    

# Execute functions
get_token()
org_info = get_org()
print(org_info)