API 1.0

API 1.0

The IoT Secure API requires an API license.  Please contact your account team for pricing and availability.

1.0 Introduction

The IoT Secure REST API (Application Programming Interface) lets you integrate IoT Secure with third-party applications including:
  1. Configuration Management Database (CMDB)
  2. Security Information and Event Management (SIEM)
  3. IT Service Management (ITSM)
The REST API uses simple HTTP methods, such as GET, POST and DELETE.  These methods allow IoT Secure data to be extracted in JSON format making it easy to develop new applications and also to integrate with existing business applications.

2.0 API Keys

To use the API, you will need a IoT Secure API Key.  The API Key is organization specific and permanent so please guard it carefully.  Contact IoT Secure Support at support@iotsecure.io to obtain your API Key.

3.0 API Limits

API License Type
API Requests -- Upper Limit
Demo License
5 requests/day/organization
Developer License
50 requests/day/organization
Enterprise License
5,000 requests/day/organization

A day is defined as 00:00:00 UTC - 23:59:59 UTC.  You will receive the following API response when your daily API request limit has been reached.

{
    "apikey": "XXXXX",
    "account_name": "XXXXX",
    "request_limit": XXXXX,
    "request_status": "failed",
    "request_status_code": 400,
    "request_status_detail": "API request limit reached. Try again tomorrow. See KnowledgeBase: https://tickets.iotsecure.io/portal/en/kb/articles/api-1-0"
}

4.0 API URL

https://api1.iotsecure.io/

5.0 API Modules, Actions, Search Filters & Fields


Module Name
Description
Account
Account Settings API
IoTSecurity
IoT Securit API
LogManagement
Log Management API


5.1 Account API

Action Name
     |- Field Name
Required
Description
countAPIKeys

Retrieve the number of API keys for an account
     |- apikey_count


listAPIKeys

Retrieve all API keys for an organization
     |- apikeys


getAPIKey

Retrieves an individual API key record
     |- account_name

Account name registered to API key
     |- request_limit

Request limit/day
     |- requests

Requests made during current day
     |- status

API key status

  1. ### Sample Request:
    ### Request number of API keys for an organization

    curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=Account&action=countAPIKeys"

    ### Sample Response:
    {
      "apikey_count": 1
    }

  1. ### Sample Request:
    ### Request API keys for an organization

    curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=Account&action=listAPIKeys"

    ### Sample Response:
    {
      "apikeys": [
        "XXXXX"
      ]
    }

  1. ### Sample Request:
    ### Request API key detail for XXXXX

    curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=Account&action=getAPIKey"

    ### Sample Response:
    {
      "account_name": "Demo Company",
      "request_limit": 5000,
      "requests": 439,
      "status": "active"
    }

5.2 IoT Security API

Action Name
     |- Search Filter Name
Required
Description
countAlerts

Retrieve the number of alerts for an account
listAlerts

To retrieve all IoT security alerts for an organization
     |- created
No
Time  (Epoch)
     |- modified
No
Time  (Epoch)
listDevices

To retrieve all devices for an organization
     |- created
No
Time  (Epoch)
     |- modified
No
Time  (Epoch)
     |- category
No
IoT Secure
     |- type
No
IoT Secure
     |- threat
No
true/false
listSNMPProfiles

To retrieve all SNMP profiles for an organization
     |- created
No
Time  (Epoch)
     |- modified
No
Time  (Epoch)
getAlert

To retrieve an individual alert record
     |- alert_id
Yes

getDevice

To retrieve an individual device record
     |- device_id
Yes

getSNMPProfile

To retrieve an individual SNMP profile record
     |- snmp_profile
Yes

getDeviceTimeline

To retrieve the Timeline logs for an individual device
     |- device_id
Yes

     |- hours
Yes
How far back to get results (hours)
updateDevice

To update an individual device record
     |- device_id
Yes
Device to update
     |- name
No
New device name
     |- snmp_profile
No
New SNMP profile


Action Name
     |- Field Name
Description
getAlert

     |- alert_id
Alert ID  (unique)
     |- category
Alert category  (list of alert categories)
     |- category_detail
Alert
     |- created
Created  (Epoch)
     |- device_id
MAC address
     |- modified
Last modified  (Epoch)
     |- port

     |- priority
Alert priority
     |- resolution
Alert resolution
     |- status
Alert status  (list of alert status)
     |- subject
Alert subject
getDevice

     |- blocked
Device currently blocked  (true/false)
     |- category
Device category
     |- created
Created  (Epoch)
     |- device_id
MAC address  (unique)
     |- domains
Domains queried by device
     |- excluded
Excluded from inspection  (true/false)
     |- hostname
Hostname
     |- ip_address
IP address
     |- last_active
Last seen  (Epoch)
     |- location
Network location
     |- manufacturer
Device manufacturer
     |- model
Device model
     |- model_family
Device model family
     |- model_number
Device model number
     |- modified
Last modified  (Epoch)
     |- name
Device name
     |- os_build
Operating system build
     |- os_manufacturer
Operating system manufacturer
     |- os_servicepack
Operating system service pack
     |- os_type
Operating system type
     |- os_version_major
Operating system version  (major)
     |- os_version_minor
Operating system version  (minor)
     |- oui
Network card manufacturer. NOT the device manufacturer.
     |- portsafe_inspection.last_auto_inspection
Last system automated PortSafe inspection (Epoch)
     |- portsafe_inspection.last_user_inspection
Last user requested PortSafe inspection (Epoch)
     |- portsafe_results.ports
Last PortSafe inspection results
     |- smart_blocked
Device is being smart blocked  (true/false)
     |- snmp_profile
Current SNMP profile
     |- spoofed
Device is being spoofed  (true/false)
     |- threat
Device has current threat  (true/false)
     |- type
Device type
getSNMPProfile

     |- community
SNMP community
     |-connection_attempts
Max SNMP connection attempts
     |-connection_timeout
Max SNMP connection timeout
     |-created
Created  (Epoch)
     |-created_by

     |-default
Organization's default SNMP profile
     |-modified
Last Modified (Epoch)
     |-modified_by

     |-port
SNMP port
     |-snmp_profile
Profile Name
     |-version
SNMP version
getDeviceTimeline

     |- event.created
Created  (UTC)
     |- event.device_id
MAC address
     |- event.ip_address
IP address
     |- event.status
Up/down status of device


  1. ### Sample Request:
    ### Count Alerts

    curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=IoTSecurity&action=countAlerts"

    ### Sample Response:
    {
      "alert_count": 87
    }

  1. ### Sample Request:
    ### Request Alerts

    curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=IoTSecurity&action=listAlerts"

    ### Sample Response:

    {
      "alerts": [
        "900451",
        "900464"
      ]
    }



5.3 Log Management API

Action Name
     |- Search Filter Name
Required
Description
getLogStats

To retrieve log management statistics

Learn more about UNIX Epoch time on Wikipedia.

6.0 Additional API Request Examples



### Sample Request:
### Request Alerts

curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=IoTSecurity&action=listAlerts"

### Sample Response:

{
  "alerts": [
    "900451",
    "900464"
  ]
}


### Sample Request:
### Request devices created after January 1, 2022

curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=IoTSecurity&action=listDevices&created=1641013200"

### Sample Response:

{
  "devices": [
    "00:01:3E:02:00:00",
    "04:79:70:20:00:00",
    "08:F4:AB:57:00:00",
    "10:D0:7A:C2:00:00",
    "00:40:17:6C:00:00"
  ]
}



### Sample Request:
### Request devices modified after February 1, 2019 AND where device type is Electrocardiogram

curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=IoTSecurity&action=listDevices&modified=1548997200&type=Electrocardiogram"


### Sample Response:

{
  "devices": [
    "00:01:3E:02:00:00",
    "04:79:70:20:00:00",
    "00:40:17:6C:00:00"
  ]
}



### Sample Request:
### Request device detail for 00:40:17:6C:00:00

curl -X GET -L "https://api1.iotsecure.io/?apikey=XXXXX&module=IoTSecurity&action=getDevice&device_id=00:40:17:6C:00:00"


### Sample Response:

{
    "blocked": false,
    "category": "Medical Device",
    "created": 1498767515,
    "device_id": "00:40:17:6C:00:00",
    "domains": [
        "ge.com",
        "gehealth.com"
    ],
    "excluded": false,
    "hostname": "ECG001",
    "ip_address": "192.168.121.15",
    "last_active": 1550716545,
    "location": "ER Wifi",
    "manufacturer": "GE Healthcare",
    "model": "Resting ECG",
    "model_family": "MAC",
    "model_number": null,
    "modified": 1550637634,
    "name": "GE Healthcare Resting ECG",
    "os_build": null,
    "os_manufacturer": null,
    "os_servicepack": null,
    "os_type": "Linux",
    "os_version_major": null,
    "os_version_minor": null,
    "oui": "Silex Technology America",
    "portsafe_inspection": {
        "last_auto_inspection": 1550370986,
        "last_user_inspection": 1550434500
    },
    "portsafe_results" : {
        "22" : {
           "status" : "open",
            "protocol" : "tcp",
            "service" : "ssh",
            "exploitable" : false
        },
        "23" : {
            "status" : "open",
            "protocol" : "tcp",
            "service" : "telnet",
            "exploitable" : false
        },
        "80" : {
            "status" : "open",
            "protocol" : "tcp",
            "service" : "http",
            "exploitable" : false
        },
        "443" : {
            "status" : "open",
            "protocol" : "tcp",
            "service" : "http",
            "certificate" : "Subject:commonName=GE-ECG/countryName=GB;;Issuer:commonName=GE-ECG/countryName=GB;;Signature Algorithm:sha256WithRSAEncryption",
            "exploitable" : true
        },
        "161" : {
            "status" : "open",
            "protocol" : "udp",
            "service" : "snmp",
            "exploitable" : false
        }
    },
    "smart_blocked": false,
    "snmp_profile": "IoT Secure AutoDetect",
    "spoofed": true,
    "threat": false,
    "type": "Electrocardiogram"
}



### Sample Request:
### Request Timeline activity for the past 24 hours

curl -X GET -L --insecure --verbose "https://api1.iotsecure.io/" \
   --data "apikey=XXXXX" \
   --data "module=IoTSecurity" \
   --data "action=getDeviceTimeline" \
   --data "device_id=00:40:17:6C:00:00" \
   --data "hours=24"


### Sample Response:

{
  "prtsafe_inspection": {
    "created": "2019-01-15T20:10:00.000Z",
    "device_id": "00:40:17:6C:00:00",
    "ip_address": "192.168.121.15",
    "status": "up"
  }
}



### Sample Request:
### Update device name

curl -X GET -L --insecure --verbose "https://api1.iotsecure.io/" \
   --data "apikey=XXXXX" \
   --data "module=IoTSecurity" \
   --data "action=updateDevice" \
   --data "device_id=00:40:17:6C:00:00" \
   --data "name=ICU Infusion Pump 5"


### Sample Response:

{
  "action": "updateDevice",
  "device_id": "00:40:17:6C:00:00",
  "request_status": "success"
}



### Sample Request:
### Update device SNMP Profile

curl -X GET -L --insecure --verbose "https://api1.iotsecure.io/" \
   --data "apikey=XXXXX" \
   --data "module=IoTSecurity" \
   --data "action=updateDevice" \
   --data "device_id=00:40:17:6C:00:00" \
   --data "snmp_profile=NewProfile"


### Sample Response:

{
  "action": "updateDevice",
  "device_id": "00:40:17:6C:00:00",
  "request_status": "success"
}


7.0 Frequently Asked Questions (FAQs)

API request failure.
When an API request fails, a properly formatted JSON response is returned.  This response should help you isolate the problem.

{
    "request_status": "failed",
    "request_status_code": 500,
    "request_status_detail": "Invalid API key. See KnowledgeBase for help: https://tickets.iotsecure.io/portal/en/kb/iotsecure/api"
}


Making API requests when query elements contain a space.
When requesting a value with a space, replace all spaces with '%20' before submitting the request.

### Requesting a single term device type
### Device Type: Electrocardiogram

type=Electrocardiogram


### Requesting a multi term device type with a space
### Device Type: Logic Controller

type=Logic%20Controller