Get Device

Use this endpoint to get a specific device.

URL

https://{{HOST}}/security/device?v=2{version}&deviceId={deviceId}&includeKeys={{bool}}'

Method

GET

Required IMS Scopes

  • securityapi_all

Versions Supported

  • 2.0 (Default)

URL Query Parameters

Name Description Example Type
v
optional		 Version of the api to use /device?v=2.0 number
deviceId
required		 Retrieves a specific device string
includeKeys
optional		 Defaults to false. Set to true to include device primary and secondary keys. bool

Request Header Parameters

Type Value Description
Authorization
required		 Bearer {access_token} IMS access token

Example

Request

curl -X GET 
  'https://{{HOST}}/securityapi/device?v=2.0&deviceId=device2&includeKeys=false' 
  -H 'Authorization: Bearer {access_token}'

Response

{
    "properties": {
        "DeviceID": "device2",
        "HubEnabledState": null,
        "CreatedTime": "2018-03-27T14:28:38.1613939Z",
        "DeviceState": "normal",
        "UpdatedTime": "2018-03-27T14:30:38.2250125Z"
    },
    "commands": [],
    "telemetries": null,
    "shadow": {
        "revision": 0,
        "schemaVersion": 1,
        "deviceType": 0
    },
    "id": "device2",
    "subject": "6273d6a9-8ba5-4195-9526-5a73c1d37ff0",
    "organization": "jci.com"
}

Errors

Error Description
Error Name Description of Error

Response Body Parameters

Name Schema Description
Id String Friendly identifier. Identifies the device name in IoT Hub.
PrimaryKey Base64 String Used to securely communicate to IoT Hub. If omitted on creation, the API generates one.
SecondaryKey Base64 String Used when changing the PrimaryKey, but is not needed for general communication. If omitted, the API generates one.
Properties JSON Object Used to store any metadata for the device.
Commands JSON Array Used to define supported commands for the device.
Telemetries JSON Array Used to show mapped telemetries for the device.
Status JSON Object Used to show the status for the device.