Update device by ID (client authentication)

Endpoint URL

generic

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

Updates field values for an existing device. Optionally, updates the device name (or device_identifier). The device ID cannot be changed.

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_write 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.

The Update device operation is destructive to the fields array. The field values in your request overwrite existing field values for the device. Omitting field values from the request causes existing values to be deleted.

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 PUT 'https://clientauth.one.digicert.com/iot/api/v2/device/{{device_id}}' \
--header 'Content-Type: application/json' \
--key {{my_private_key.key}} \
--cert {{my_custom_certificate.pem}} \
--data-raw '{
  "device_identifier": "New Device",
  "fields": [
    {
      "id": "417c328e-604c-4e94-9112-ee58f12277fb",
      "value": "updated mandatory value"
    },
    {
      "id": "90eb4de2-ae8a-48a0-a904-d30c5ab6e1de",
      "value": "updated optional value"
    }
  ]
}'

201 Created

{
  "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": true
}

400 Bad Request

{
  "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 update. To get a list of devices and their IDs, use the Device list endpoint.

Request parameters

Name	Req/Opt	Type	Description
device_identifier	optional	string	New name for the device.
fields	defined in device profile	array	Array of fields that describe device attributes and settings.
.. id	-	string	Existing field ID as defined in the device profile. To get field IDs for a device, use the Get device details endpoint.
.. value	-	string	New field value. Character limit: 1024

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 device was created. Format: UTC time zone and ISO 8601 date
updated	string	Date and time 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.

Endpoint URL

Example requests and responses

Path parameters

Request parameters

Response parameters

Informazioni