Share via

Devices - Create Or Update Identity

Service:
IoT Hub
API Version:
2021-04-12

Creates or updates the identity of a device in the identity registry of the IoT Hub.

PUT https://fully-qualified-iothubname.azure-devices.net/devices/{id}?api-version=2021-04-12

URI Parameters

Name In Required Type Description
id
 path True

string

The unique identifier of the device.
api-version
 query True

string

Version of the Api.

Request Header

Name Required Type Description
If-Match

string

The string representing a weak ETag for the device identity, as per RFC7232. This should not be set when creating a device, but may be set when updating a device.

Request Body

Name Type Description
authentication

AuthenticationMechanism

The authentication mechanism used by the device.
capabilities

DeviceCapabilities

The set of capabilities of the device. For example, if this device is an edge device or not.
cloudToDeviceMessageCount

integer (int32)

The number of cloud-to-device messages currently queued to be sent to the device.
connectionState enum:
  • Disconnected
  • Connected

The state of the device.
connectionStateUpdatedTime

string (date-time)

The date and time the connection state was last updated.
deviceId

string

The unique identifier of the device.
deviceScope

string

The scope of the device. Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship.
etag

string

The string representing a weak ETag for the device identity, as per RFC7232.
generationId

string

The IoT Hub-generated, case-sensitive string up to 128 characters long. This value is used to distinguish devices with the same deviceId, when they have been deleted and re-created.
lastActivityTime

string (date-time)

The date and last time the device last connected, received, or sent a message.
parentScopes

string[]

The scopes of the upper level edge devices if applicable. Only available for edge devices.
status enum:
  • enabled
  • disabled

The status of the device. If the status disabled, a device cannot connect to the service.
statusReason

string

The 128 character-long string that stores the reason for the device identity status. All UTF-8 characters are allowed.
statusUpdatedTime

string (date-time)

The date and time when the status field was last updated.

Responses

Name Type Description
200 OK

Device

OK.

Definitions

Name Description
AuthenticationMechanism
Device
DeviceCapabilities

The status of capabilities enabled on the device.
SymmetricKey
X509Thumbprint

AuthenticationMechanism

Object
Name Type Description
symmetricKey

SymmetricKey

The primary and secondary keys used for SAS based authentication.
type enum:
  • certificateAuthority
  • none
  • sas
  • selfSigned

The type of authentication used to connect to the service.
x509Thumbprint

X509Thumbprint

The primary and secondary x509 thumbprints used for x509 based authentication.

Device

Object
Name Type Description
authentication

AuthenticationMechanism

The authentication mechanism used by the device.
capabilities

DeviceCapabilities

The set of capabilities of the device. For example, if this device is an edge device or not.
cloudToDeviceMessageCount

integer (int32)

The number of cloud-to-device messages currently queued to be sent to the device.
connectionState enum:
  • Connected
  • Disconnected

The state of the device.
connectionStateUpdatedTime

string (date-time)

The date and time the connection state was last updated.
deviceId

string

The unique identifier of the device.
deviceScope

string

The scope of the device. Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship.
etag

string

The string representing a weak ETag for the device identity, as per RFC7232.
generationId

string

The IoT Hub-generated, case-sensitive string up to 128 characters long. This value is used to distinguish devices with the same deviceId, when they have been deleted and re-created.
lastActivityTime

string (date-time)

The date and last time the device last connected, received, or sent a message.
parentScopes

string[]

The scopes of the upper level edge devices if applicable. Only available for edge devices.
status enum:
  • disabled
  • enabled

The status of the device. If the status disabled, a device cannot connect to the service.
statusReason

string

The 128 character-long string that stores the reason for the device identity status. All UTF-8 characters are allowed.
statusUpdatedTime

string (date-time)

The date and time when the status field was last updated.

DeviceCapabilities

Object

The status of capabilities enabled on the device.

Name Type Description
iotEdge

boolean

The property that determines if the device is an edge device or not.

SymmetricKey

Object
Name Type Description
primaryKey

string

The base64 encoded primary key of the device.
secondaryKey

string

The base64 encoded secondary key of the device.

X509Thumbprint

Object
Name Type Description
primaryThumbprint

string

The X509 client certificate primary thumbprint.
secondaryThumbprint

string

The X509 client certificate secondary thumbprint.