Runtime Registration - Register Device

Service:: IoT Hub Device Provisioning Service

API Version:: 2021-10-01

Registers the devices.

PUT https://global.azure-devices-provisioning.net/{idScope}/registrations/{registrationId}/register?api-version=2021-10-01

URI Parameters

Name	In	Required	Type	Description
idScope	path	True	string	The scope of the DPS instance.
registrationId	path	True	string	The registration ID is alphanumeric, lowercase, and may contain hyphens.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Type	Description
payload		Any object
registrationId	string	The registration ID is a case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
tpm	TpmAttestation	Attestation via TPM.

Responses

Name	Type	Description
200 OK	RegistrationOperationStatus	The request has succeeded.
202 Accepted	RegistrationOperationStatus	The request has been accepted for processing, but processing has not yet completed. Headers Location: string retry-after: integer
Other Status Codes	ProvisioningServiceErrorDetails	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

RegistrationOperationStatus

The request has succeeded.

202 Accepted

RegistrationOperationStatus

The request has been accepted for processing, but processing has not yet completed.

Headers

Location: string
retry-after: integer

Other Status Codes

ProvisioningServiceErrorDetails

An unexpected error response.

Headers

x-ms-error-code: string

Examples

RuntimeRegistration_RegisterDevice_MaximumSet_Gen

RuntimeRegistration_RegisterDevice_MinimumSet_Gen

RuntimeRegistration_RegisterDevice_MaximumSet_Gen

Sample request

HTTP

PUT https://global.azure-devices-provisioning.net/ofvgihmgllfsmm/registrations/macgmlbhpb/register?api-version=2021-10-01

{
  "payload": {},
  "registrationId": "qypnuerjeunzogqdezhjgisfr",
  "tpm": {
    "endorsementKey": "sbvvzftylrpsetexcmnijtdezppq",
    "storageRootKey": "juohyrayid"
  }
}

Sample response

Status code:: 200

{
  "operationId": "xosjboksmobnotwgqejpvxiwi",
  "registrationState": {
    "assignedHub": "ljexps",
    "createdDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "deviceId": "hjvdlwpugzlk",
    "errorCode": 13,
    "errorMessage": "zpctqazbkbiqjkwosis",
    "etag": "hjtelksspyfzhmet",
    "lastUpdatedDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "payload": {},
    "registrationId": "urejrffpkqneou",
    "status": "unassigned",
    "substatus": "initialAssignment",
    "symmetricKey": {
      "enrollmentGroupId": "w"
    },
    "tpm": {
      "authenticationKey": "sofbxakhjrxpiyysjjxkx"
    },
    "x509": {
      "certificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      },
      "enrollmentGroupId": "qbw",
      "signingCertificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      }
    }
  },
  "status": "unassigned"
}

Status code:: 202

{
  "operationId": "xosjboksmobnotwgqejpvxiwi",
  "registrationState": {
    "assignedHub": "ljexps",
    "createdDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "deviceId": "hjvdlwpugzlk",
    "errorCode": 13,
    "errorMessage": "zpctqazbkbiqjkwosis",
    "etag": "hjtelksspyfzhmet",
    "lastUpdatedDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "payload": {},
    "registrationId": "urejrffpkqneou",
    "status": "unassigned",
    "substatus": "initialAssignment",
    "symmetricKey": {
      "enrollmentGroupId": "w"
    },
    "tpm": {
      "authenticationKey": "sofbxakhjrxpiyysjjxkx"
    },
    "x509": {
      "certificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      },
      "enrollmentGroupId": "qbw",
      "signingCertificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      }
    }
  },
  "status": "unassigned"
}

RuntimeRegistration_RegisterDevice_MinimumSet_Gen

Sample request

HTTP

PUT https://global.azure-devices-provisioning.net/gwgyqmyyzzzjpjmxml/registrations/tuodrxicixbbekaajxfiyvoxsbe/register?api-version=2021-10-01

{}

Sample response

Status code:: 200

{
  "operationId": "xosjboksmobnotwgqejpvxiwi"
}

Status code:: 202

{
  "operationId": "xosjboksmobnotwgqejpvxiwi"
}

Definitions

Name	Description
AssignedDeviceSubstatus	Substatus for 'Assigned' devices. Possible values include - 'initialAssignment': Device has been assigned to an IoT hub for the first time, 'deviceDataMigrated': Device has been assigned to a different IoT hub and its device data was migrated from the previously assigned IoT hub. Device data was removed from the previously assigned IoT hub, 'deviceDataReset': Device has been assigned to a different IoT hub and its device data was populated from the initial state stored in the enrollment. Device data was removed from the previously assigned IoT hub, 'reprovisionedToInitialAssignment': Device has been re-provisioned to a previously assigned IoT hub.
DeviceRegistration	Device registration.
DeviceRegistrationResult	Device registration result.
EnrollmentStatus	Enrollment status.
ProvisioningServiceErrorDetails	Contains the properties of an error returned by the Azure IoT Hub Provisioning Service.
RegistrationOperationStatus	Registration operation status.
SymmetricKeyRegistrationResult	Registration result returned when using SymmetricKey attestation.
TpmAttestation	Attestation via TPM.
TpmRegistrationResult	TPM registration result.
X509CertificateInfo	X509 certificate info.
X509RegistrationResult	X509 registration result.

AssignedDeviceSubstatus

Enumeration

Substatus for 'Assigned' devices. Possible values include - 'initialAssignment': Device has been assigned to an IoT hub for the first time, 'deviceDataMigrated': Device has been assigned to a different IoT hub and its device data was migrated from the previously assigned IoT hub. Device data was removed from the previously assigned IoT hub, 'deviceDataReset': Device has been assigned to a different IoT hub and its device data was populated from the initial state stored in the enrollment. Device data was removed from the previously assigned IoT hub, 'reprovisionedToInitialAssignment': Device has been re-provisioned to a previously assigned IoT hub.

Value	Description
initialAssignment	initialAssignment
deviceDataMigrated	deviceDataMigrated
deviceDataReset	deviceDataReset
reprovisionedToInitialAssignment	reprovisionedToInitialAssignment

DeviceRegistration

Object

Device registration.

Name	Type	Description
payload		Any object
registrationId	string	The registration ID is a case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
tpm	TpmAttestation	Attestation via TPM.

DeviceRegistrationResult

Object

Device registration result.

Name	Type	Description
assignedHub	string	Assigned Azure IoT Hub.
createdDateTimeUtc	string (date-time)	Registration create date time (in UTC).
deviceId	string	Device ID.
errorCode	integer (int32)	Error code.
errorMessage	string	Error message.
etag	string	The entity tag associated with the resource.
lastUpdatedDateTimeUtc	string (date-time)	Last updated date time (in UTC).
payload		Any object
registrationId	string	This id is used to uniquely identify a device registration of an enrollment. A case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
status	EnrollmentStatus	Enrollment status.
substatus	AssignedDeviceSubstatus	Substatus for 'Assigned' devices. Possible values include - 'initialAssignment': Device has been assigned to an IoT hub for the first time, 'deviceDataMigrated': Device has been assigned to a different IoT hub and its device data was migrated from the previously assigned IoT hub. Device data was removed from the previously assigned IoT hub, 'deviceDataReset': Device has been assigned to a different IoT hub and its device data was populated from the initial state stored in the enrollment. Device data was removed from the previously assigned IoT hub, 'reprovisionedToInitialAssignment': Device has been re-provisioned to a previously assigned IoT hub.
symmetricKey	SymmetricKeyRegistrationResult	Registration result returned when using SymmetricKey attestation.
tpm	TpmRegistrationResult	TPM registration result.
x509	X509RegistrationResult	X509 registration result.

EnrollmentStatus

Enumeration

Enrollment status.

Value	Description
unassigned	unassigned
assigning	assigning
assigned	assigned
failed	failed
disabled	disabled

ProvisioningServiceErrorDetails

Object

Contains the properties of an error returned by the Azure IoT Hub Provisioning Service.

Name	Type	Description
errorCode	integer (int32)	Numeric error code.
info	object	Dictionary of <string>
message	string	Error message.
timestampUtc	string (date-time)	Error timestamp (UTC).
trackingId	string	Error tracking ID.

RegistrationOperationStatus

Object

Registration operation status.

Name	Type	Description
operationId	string minLength: 1	Operation ID.
registrationState	DeviceRegistrationResult	Device registration result.
status	EnrollmentStatus	Device enrollment status.

SymmetricKeyRegistrationResult

Object

Registration result returned when using SymmetricKey attestation.

Name	Type	Description
enrollmentGroupId	string	Enrollment group ID.

TpmAttestation

Object

Attestation via TPM.

Name	Type	Description
endorsementKey	string	TPM endorsement key.
storageRootKey	string	TPM storage root key.

TpmRegistrationResult

Object

TPM registration result.

Name	Type	Description
authenticationKey	string	Encrypted authentication key.

X509CertificateInfo

Object

X509 certificate info.

Name	Type	Description
issuerName	string	Certificate issuer name.
notAfterUtc	string (date-time)	Certificate expiry date (UTC).
notBeforeUtc	string (date-time)	Certificate validity start date (UTC).
serialNumber	string	Certificate serial number.
sha1Thumbprint	string	SHA-1 thumbprint of the certificate.
sha256Thumbprint	string	SHA-256 thumbprint of the certificate.
subjectName	string	Certificate subject name.
version	integer (int32)	Certificate version.

X509RegistrationResult

Object

X509 registration result.

Name	Type	Description
certificateInfo	X509CertificateInfo	X509 certificate info.
enrollmentGroupId	string	Enrollment group ID.
signingCertificateInfo	X509CertificateInfo	X509 certificate info.