How to Connect a System to Cloud using the REST API?

Overview

In some development scenarios, it may be necessary to programmatically connect a System to Cloud. This article provides guidance on how to automate the process of connecting one or more Systems to Cloud using the APIs. The information is intended for the users who are looking to streamline cloud onboarding and integration workflows.

How It Works

Connecting a System to Cloud involves the following key steps:

1. Authenticate with Cloud to obtain an OAuth token.
2. Bind a System to the Cloud to retrieve the cloudSystemId and authKey.
3. Create a local admin login session on the target System.
4. Execute the request to complete the procedure of System connection to Cloud.

This automation is useful for provisioning and registering multiple systems without manual UI-based setup.

1. Authenticate with Cloud:
   1. Use CDB API to get the bearer token for rest of requests.
   2. Use the API : POST /cdb/oauth2/token  
   3. The access token in the response would be used for the request.
2. Initiate the binding request to the Cloud:
   1. Use the access_token acquired in step1.
   2. If a System is connected to personal account - POST /cdb/systems/bind
   3. If a System is connected to an organization - POST /partners/api/v3/cloud_systems/
   4. The response will contain the id, ownerAccountEmail and authKey.
3. Create a local admin login session :
   1.  
      1. Use the Mediaserver REST API : POST /rest/v3/login/sessions
      2. The token in the response would be used for the next request.
4. Execute the request to complete the procedure:
   1.  
      1. Use the token acquired in step3.
      2. If the System is a new one, user the API : POST /rest/v3/system/setup
      3. If the System is an existed one, user the API : POST /rest/v3/system/cloud/bind 

Sample Script 

1. For a New System to Cloud (example Python script, connect to personal account)

# This script configures and adds a NEW System to Cloud

import requests

SERVER_URL = "https://localhost:7001"
CLOUD_URL = "https://nxvms.com"
SYSTEM_NAME = "some_system"
CUSTOMIZATION = "default" #default for "Nx Witness"
CLOUD_USER = "cloud_account@networkoptix.com"
CLOUD_PASS = "some_password"
SYSTEM_LOGIN = "admin"
SYSTEM_PASSWORD = "some_password_for_admin"

###################################
# step 1: Authenticate with Cloud.#
###################################
oauth_request = requests.post(f"{CLOUD_URL}/cdb/oauth2/token",
    json={
        "grant_type": "password",
        "response_type": "token",
        "client_id": "3rdParty",
        "scope": f"{CLOUD_URL} cloudSystemId=*",
        "username": CLOUD_USER,
        "password": CLOUD_PASS
    }
)

#####################################################
# step 2: Initiate the binding request to the Cloud.#
#####################################################
cloud_requests_header = {"Authorization": f"Bearer {oauth_request.json()['access_token']}"}
cloud_bind_request = requests.post(f"{CLOUD_URL}/cdb/system/bind",
    json={
        "name": SYSTEM_NAME,
        "customization": CUSTOMIZATION
    },
    headers=cloud_requests_header
)

jsonData = cloud_bind_request.json()

##############################################
# step 3:Create a local admin login session. #
##############################################
local_session_request = requests.post(f"{SERVER_URL}/rest/v3/login/sessions",
    json={
        "username": SYSTEM_LOGIN,
        "password": SYSTEM_PASSWORD
    },
    verify=False
)

#########################################################
# step 4: Execute the request to complete the procedure.##########################################################
local_request_headers = {"Authorization": f"Bearer {local_session_request.json()['token']}" }

setup_payload = {
    "name": SYSTEM_NAME,
    "settings": {
        "autoDiscoveryEnabled": True,
        "cameraSettingsOptimization": True,
        "statisticsAllowed": True
    },
    "cloud": {
        "systemId": jsonData["id"],
        "authKey": jsonData["authKey"],
        "owner": jsonData["ownerAccountEmail"]
    }
}

local_setup_request = requests.post(f"{SERVER_URL}/rest/v3/system/setup",
    json=setup_payload,
    headers=local_request_headers,
    verify=False
)

2. For an Existing System to Cloud, on step 4, we use different APIs to complete the binding procedure.

# This script configures and adds ax EXISTING System to Cloud

# ...
# Step 1 ~ Step 3 are the same
# ...

#########################################################
# step 4: Execute the request to complete the procedure.##########################################################
local_request_headers = {"Authorization": f"Bearer {local_session_request.json()['token']}" }

setup_payload = {
    "systemId": jsonData["id"],
    "authKey": jsonData["authKey"],
    "owner": jsonData["ownerAccountEmail"]
}

local_setup_request = requests.post(f"{SERVER_URL}/rest/v3/system/cloud/bind",
    json=setup_payload,
    headers=local_request_headers,
    verify=False
)

Note: The default port 7001. If this port has been changed, update the script’s URL accordingly (e.g., https://localhost:<port>). The script must be run on the same machine as the target server when using localhost.

If you intend to run the script from a different machine, replace localhost with the actual IP address of the server.