Defender for IoT API reference
This section describes the public APIs supported by Microsoft Defender for IoT. Defender for IoT APIs are governed by Microsoft API License and Terms of use.
Use Defender for IoT APIs to access data discovered by sensors and on-premises management consoles and perform actions with that data.
API connections are secured over SSL.
Generate an API access token
Many Defender for IoT APIs require an access token. Access tokens are not required for authentication APIs.
To generate a token:
In the System Settings window, select Integrations > Access Tokens.
Select Generate token.
In Description, describe what the new token is for, and select Generate.
The access token appears. Copy it, because it won't be displayed again.
Select Finish.
The tokens that you create appear in the Access Tokens dialog box. The Used indicates the last time an external call with this token was received.
N/A in the Used field indicates that the connection between the sensor and the connected server isn't working.
After generating the token, add an HTTP header titled Authorization to your request, and set its value to the token that you generated.
Sensor API version reference
| Version | Supported APIs |
|---|---|
| No version | Authentication and password management: - set_password (Change your password) - set_password_by_admin (Update a user password by admin) - validation (Validate user credentials) |
| New in version 1 | Inventory: - connections (Retrieve device connection information) - cves (Retrieve information on CVEs) - devices (Retrieve device information) Alerts: - alerts (Retrieve alert information) - events (Retrieve timeline events) Vulnerabilities: - operational (Retrieve operational vulnerabilities) - devices (Retrieve device vulnerability information) - mitigation (Retrieve mitigation steps) - security (Retrieve security vulnerabilities) |
| New in version 2 | Alerts: - Updates to alerts (Retrieve alert information) |
On-premises management console API version reference
| Version | APIs |
|---|---|
| No version | Authentication and password management: - set_password (Change password) - set_password_by_admin (User password update by system admin) - validation (Authenticate user credentials) |
| New in version 1 | Sites - appliances (Manage OT sensor appliances) Inventory: - devices (Retrieve all device information) Alerts: - alerts (Retrieve alert information) - maintenanceWindow (Create alert exclusions) |
| New in version 2 | Alerts: - Updates to alerts (Retrieve alert information) - pcap (Request alert PCAP) |
| New in version 3 | Integration APIs: - connections (Get device connections) - device (Get details for a device) - devicecves (Get device CVEs) - devices (Create and update devices) - deleteddevices (Get deleted devices) - sensors (Get sensors) |
Note
Integration APIs are meant to run continuously and create a constantly running data stream, such as to query for new data from the last five minutes. Integration APIs return data with a timestamp.
To simply query data, use the regular, non-integration APIs instead, for either an on-premises management console to query all devices, or for a specific sensor to query devices from that sensor only.
Epoch time
In all Defender for IoT timestamp values, Epoch time is equal to 1/1/1970.
Next steps
For more information, see:
- Manage your device inventory from the Azure portal
- Manage your OT device inventory from a sensor console
- Manage your OT device inventory from an on-premises management console
- View and manage alerts from the Azure portal
- View alerts on your sensor
- Work with alerts on the on-premises management console