Get device details by ID (client authentication)

Endpoint URL

generic
GET https://clientauth.one.digicert.com/iot/api/v2/device/{{device_id}}

Use this endpoint to get device details by ID, including status and attributes.

This endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.

Use TLS authentication when:

  • You need to configure a device to read and update its own data.
  • You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.

To access this endpoint with TLS authentication:

  • The certificate in the API request must be a certificate that is associated with the device.
  • The device_api_allow_read property for the device must be set to true.
    To change the value of this property, use the Update device by ID endpoint. Alternatively, edit the settings for the device from the IoT Device Manager console.

Example requests and responses

To use this example, replace {{my_private_key.key}} and {{my_custom_certificate.pem}} with the filenames or path to the location for your private key and certificate.

cURL
curl -X GET 'https://clientauth.one.digicert.com/iot/api/v2/device/{{device_id}} \
--key {{my_private_key.key}} \
--cert {{my_custom_certificate.pem}}
200 OK
{
  "id": "64c02969-3890-4da8-a5ef-b574fd72887e",
  "account_id": "1d1ec1ec-6502-11e9-a923-1681be663d3e",
  "division": {
    "id": "fd5faa1e-623a-47a9-831b-b9397c33395f",
    "name": "Mock Division 1"
  },
  "device_identifier": "New Device",
  "device_profile": {
    "id": "a81a431a-be7b-4f2e-8afd-b2778491511f",
    "name": "Device Profile"
  },
  "created": "2020-04-22T07:13:20Z",
  "updated": "2020-04-24T09:23:21Z",
  "status": "ACTIVE",
  "fields": [
    {
      "id": "417c328e-604c-4e94-9112-ee58f12277fb",
      "name": "Mandatory Field",
      "value": "updated mandatory value",
      "mandatory": true
    },
    {
      "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de",
      "name": "Optional Field",
      "value": "updated optional value",
      "mandatory": false
    }
  ]
  "device_api_allow_read": true,
  "device_api_allow_write": true,
  "device_api_allow_renew_certificate": false
}
403 access_denied
{
  "errors": [
    {
      "code": "access_denied",
      "message": "Access denied"
    }
  ]
}
404 entity_not_found
{
  "errors": [
    {
      "code": "entity_not_found",
      "message": "Device with id {{device_id}} does not exist"
    }
  ]
}

Path parameters

Name Req/Opt Description
device_id required The unique ID of the device to query.
To get a list of devices and their IDs, use the Device list endpoint.

Response parameters

Name Type Description
id string Unique device ID created for the new device.
account_id string Account ID.
division object Division container.
.. id string Division ID.
.. name string Division name.
device_identifier string Unique device name.
device_profile object Device profile container.
.. id string Device profile ID.
.. name string Device profile name.
created string Date and time (UTC) device was created.
Format: UTC time zone and ISO 8601 date
updated string Date and time (UTC) device was last updated.
Format: UTC time zone and ISO 8601 date
status string Device status.
fields array Array of fields that describe device attributes and settings.
.. id string Unique field ID.
.. name string Field name.
.. value string Field value.
.. mandatory boolean Whether or not the field is required, based on the device profile.
device_api_allow_read boolean Whether the device can read its own device information.
This setting applies to calls on the Get device details by ID (client authentication) endpoint that use TLS authentication.
device_api_allow_write boolean Whether the device can update its own device information.
This setting applies to calls on the Update device by ID (client authentication) endpoint that use TLS authentication.
device_api_allow_renew_certificate boolean Whether the device can renew its own certificates.
This setting applies to calls on the Renew device certificate by device ID (client authentication) endpoint that use TLS authentication.