Getting Started

This page will help you get started with the InsightCloudSec API

Overview

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.

📘

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

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 and path for each endpoint, there is a request body example on the left and a response body example on the right. Some endpoints have auto-generated request body examples (typically when there are multiple different language samples available). Below the examples are the parameters available for the request. If the endpoint contains a v3 in the path and the example is auto-generated, there will be text fields next to the parameters, which will update the example code when edited. Note: Click "Suggest Edits" next to an endpoint's title to provide feedback for that endpoint.

📘

Viewing Request Body Examples

If an request body example is not loaded upon viewing an endpoint, click one of the languages along the top of the request body section.

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

🚧

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

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 DivvyCloud 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

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 DivvyCloud 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)