{ "swagger": "2.0", "info": { "title": "ProvisioningDeviceClient", "version": "2026-11-01", "description": "API for device runtime operations with the Azure IoT Hub Device Provisioning\nService", "x-typespec-generated": [ { "emitter": "@azure-tools/typespec-autorest" } ] }, "schemes": [ "https" ], "host": "global.azure-devices-provisioning.net", "produces": [ "application/json" ], "consumes": [ "application/json" ], "tags": [], "paths": { "/{idScope}/registrations/{registrationId}": { "post": { "operationId": "RuntimeRegistration_DeviceRegistrationStatusLookup", "summary": "Gets the device registration status.", "description": "Gets the device registration status.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "registrationId", "in": "path", "description": "Registration ID.", "required": true, "type": "string" }, { "name": "idScope", "in": "path", "description": "The scope of the DPS instance.", "required": true, "type": "string" }, { "name": "body", "in": "body", "description": "Device registration.", "required": true, "schema": { "$ref": "#/definitions/DeviceRegistration" } } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/DeviceRegistrationResult" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/ProvisioningServiceErrorDetails" }, "headers": { "x-ms-error-code": { "type": "string", "description": "The error code for specific error that occurred." } } } }, "x-ms-examples": { "RuntimeRegistration_DeviceRegistrationStatusLookup_MaximumSet_Gen": { "$ref": "./examples/RuntimeRegistration_DeviceRegistrationStatusLookup_MaximumSet_Gen.json" }, "RuntimeRegistration_DeviceRegistrationStatusLookup_MinimumSet_Gen": { "$ref": "./examples/RuntimeRegistration_DeviceRegistrationStatusLookup_MinimumSet_Gen.json" } } } }, "/{idScope}/registrations/{registrationId}/operations/{operationId}": { "get": { "operationId": "RuntimeRegistration_OperationStatusLookup", "summary": "Gets the registration operation status.", "description": "Gets the registration operation status.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "registrationId", "in": "path", "description": "Registration ID.", "required": true, "type": "string" }, { "name": "operationId", "in": "path", "description": "Operation ID.", "required": true, "type": "string" }, { "name": "idScope", "in": "path", "description": "The scope of the DPS instance.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/RegistrationOperationStatus" } }, "202": { "description": "The request has been accepted for processing, but processing has not yet completed.", "schema": { "$ref": "#/definitions/RegistrationOperationStatus" }, "headers": { "Location": { "type": "string" }, "retry-after": { "type": "integer", "format": "int32" } } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/ProvisioningServiceErrorDetails" }, "headers": { "x-ms-error-code": { "type": "string", "description": "The error code for specific error that occurred." } } } }, "x-ms-examples": { "RuntimeRegistration_OperationStatusLookup_MaximumSet_Gen": { "$ref": "./examples/RuntimeRegistration_OperationStatusLookup_MaximumSet_Gen.json" }, "RuntimeRegistration_OperationStatusLookup_MinimumSet_Gen": { "$ref": "./examples/RuntimeRegistration_OperationStatusLookup_MinimumSet_Gen.json" } } } }, "/{idScope}/registrations/{registrationId}/register": { "put": { "operationId": "RuntimeRegistration_RegisterDeviceAndIssueCertificate", "summary": "Registers the devices and optionally issue operational certificates for IoT devices.", "description": "Registers the devices and optionally issue operational certificates for IoT devices.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "registrationId", "in": "path", "description": "The registration ID is alphanumeric, lowercase, and may contain hyphens.", "required": true, "type": "string" }, { "name": "idScope", "in": "path", "description": "The scope of the DPS instance.", "required": true, "type": "string" }, { "name": "body", "in": "body", "description": "Device registration request.", "required": true, "schema": { "$ref": "#/definitions/DeviceRegistration" } } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/RegistrationOperationStatus" } }, "202": { "description": "The request has been accepted for processing, but processing has not yet completed.", "schema": { "$ref": "#/definitions/RegistrationOperationStatus" }, "headers": { "Location": { "type": "string" }, "retry-after": { "type": "integer", "format": "int32" } } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/ProvisioningServiceErrorDetails" }, "headers": { "x-ms-error-code": { "type": "string", "description": "The error code for specific error that occurred." } } } }, "x-ms-examples": { "RuntimeRegistration_RegisterDeviceAndIssueCertificate_MaximumSet_Gen": { "$ref": "./examples/RuntimeRegistration_RegisterDeviceAndIssueCertificate_MaximumSet_Gen.json" }, "RuntimeRegistration_RegisterDeviceAndIssueCertificate_MinimumSet_Gen": { "$ref": "./examples/RuntimeRegistration_RegisterDeviceAndIssueCertificate_MinimumSet_Gen.json" } }, "x-ms-long-running-operation": true } } }, "definitions": { "AssignedDeviceSubstatus": { "type": "string", "description": "Substatus for 'Assigned' devices. Possible values include -\n'initialAssignment': Device has been assigned to an IoT hub for the first time,\n'deviceDataMigrated': Device has been assigned to a different IoT hub and its\ndevice data was migrated from the previously assigned IoT hub. Device data was\nremoved from the previously assigned IoT hub, 'deviceDataReset': Device has\nbeen assigned to a different IoT hub and its device data was populated from the\ninitial state stored in the enrollment. Device data was removed from the\npreviously assigned IoT hub, 'reprovisionedToInitialAssignment': Device has\nbeen re-provisioned to a previously assigned IoT hub.", "enum": [ "initialAssignment", "deviceDataMigrated", "deviceDataReset", "reprovisionedToInitialAssignment" ], "x-ms-enum": { "name": "AssignedDeviceSubstatus", "modelAsString": true, "values": [ { "name": "initialAssignment", "value": "initialAssignment", "description": "initialAssignment" }, { "name": "deviceDataMigrated", "value": "deviceDataMigrated", "description": "deviceDataMigrated" }, { "name": "deviceDataReset", "value": "deviceDataReset", "description": "deviceDataReset" }, { "name": "reprovisionedToInitialAssignment", "value": "reprovisionedToInitialAssignment", "description": "reprovisionedToInitialAssignment" } ] } }, "DeviceRegistration": { "type": "object", "description": "Device registration.", "properties": { "registrationId": { "type": "string", "description": "The registration ID is a case-insensitive string (up to 128 characters long) of\nalphanumeric characters plus certain special characters : . _ -. No special\ncharacters allowed at start or end." }, "tpm": { "$ref": "#/definitions/TpmAttestation", "description": "Attestation via TPM." }, "csr": { "type": "string", "description": "A Base64-encoded DER certificate signing request (CSR) in PKCS #10 format,\nexcluding PEM headers and footers. The Common Name (CN) must match the device\nregistrationId. Including this field in the\nRuntimeRegistration_DeviceRegistrationStatusLookup operation will result in\na bad request." }, "payload": { "type": "object", "description": "Any object", "additionalProperties": {} } } }, "DeviceRegistrationResult": { "type": "object", "description": "Device registration result.", "properties": { "tpm": { "$ref": "#/definitions/TpmRegistrationResult", "description": "TPM registration result." }, "x509": { "$ref": "#/definitions/X509RegistrationResult", "description": "X509 registration result." }, "symmetricKey": { "$ref": "#/definitions/SymmetricKeyRegistrationResult", "description": "Registration result returned when using SymmetricKey attestation." }, "registrationId": { "type": "string", "description": "This id is used to uniquely identify a device registration of an enrollment.\nA case-insensitive string (up to 128 characters long) of alphanumeric\ncharacters plus certain special characters : . _ -. No special characters\nallowed at start or end.", "readOnly": true }, "createdDateTimeUtc": { "type": "string", "format": "date-time", "description": "Registration create date time (in UTC).", "readOnly": true }, "assignedHub": { "type": "string", "description": "Assigned Azure IoT Hub.", "readOnly": true }, "deviceId": { "type": "string", "description": "Device ID.", "readOnly": true }, "status": { "$ref": "#/definitions/EnrollmentStatus", "description": "Enrollment status.", "readOnly": true }, "substatus": { "$ref": "#/definitions/AssignedDeviceSubstatus", "description": "Substatus for 'Assigned' devices. Possible values include -\n'initialAssignment': Device has been assigned to an IoT hub for the first time,\n'deviceDataMigrated': Device has been assigned to a different IoT hub and its\ndevice data was migrated from the previously assigned IoT hub. Device data was\nremoved from the previously assigned IoT hub, 'deviceDataReset': Device has\nbeen assigned to a different IoT hub and its device data was populated from the\ninitial state stored in the enrollment. Device data was removed from the\npreviously assigned IoT hub, 'reprovisionedToInitialAssignment': Device has\nbeen re-provisioned to a previously assigned IoT hub.", "readOnly": true }, "errorCode": { "type": "integer", "format": "int32", "description": "Error code.", "readOnly": true }, "errorMessage": { "type": "string", "description": "Error message.", "readOnly": true }, "lastUpdatedDateTimeUtc": { "type": "string", "format": "date-time", "description": "Last updated date time (in UTC).", "readOnly": true }, "etag": { "type": "string", "description": "The entity tag associated with the resource.", "readOnly": true }, "payload": { "type": "object", "description": "Any object", "additionalProperties": {}, "readOnly": true }, "issuedCertificateChain": { "type": "array", "description": "An array containing the full certificate chain for the issued certificate.\nThe first element is the issued leaf certificate, followed by any intermediate\ncertification authorities (ICAs), and ending with the root certification authority (CA).\nEach certificate in the array is the issuer of the previous certificate.\nThis property is not included in responses for the\nRuntimeRegistration_DeviceRegistrationStatusLookup operation.", "items": { "type": "string", "format": "byte" }, "readOnly": true } } }, "EnrollmentStatus": { "type": "string", "description": "Enrollment status.", "enum": [ "unassigned", "assigning", "assigned", "failed", "disabled" ], "x-ms-enum": { "name": "EnrollmentStatus", "modelAsString": true, "values": [ { "name": "unassigned", "value": "unassigned", "description": "unassigned" }, { "name": "assigning", "value": "assigning", "description": "assigning" }, { "name": "assigned", "value": "assigned", "description": "assigned" }, { "name": "failed", "value": "failed", "description": "failed" }, { "name": "disabled", "value": "disabled", "description": "disabled" } ] } }, "ProvisioningServiceErrorDetails": { "type": "object", "description": "Contains the properties of an error returned by the Azure IoT Hub Provisioning\nService.", "properties": { "errorCode": { "type": "integer", "format": "int32", "description": "Numeric error code." }, "trackingId": { "type": "string", "description": "Error tracking ID." }, "message": { "type": "string", "description": "Error message." }, "info": { "type": "object", "description": "Dictionary of ", "additionalProperties": { "type": "string" } }, "timestampUtc": { "type": "string", "format": "date-time", "description": "Error timestamp (UTC)." } } }, "RegistrationOperationStatus": { "type": "object", "description": "Registration operation status.", "properties": { "operationId": { "type": "string", "description": "Operation ID.", "minLength": 1 }, "status": { "$ref": "#/definitions/EnrollmentStatus", "description": "Device enrollment status." }, "registrationState": { "$ref": "#/definitions/DeviceRegistrationResult", "description": "Device registration result." } }, "required": [ "operationId" ] }, "SymmetricKeyRegistrationResult": { "type": "object", "description": "Registration result returned when using SymmetricKey attestation.", "properties": { "enrollmentGroupId": { "type": "string", "description": "Enrollment group ID." } } }, "TpmAttestation": { "type": "object", "description": "Attestation via TPM.", "properties": { "endorsementKey": { "type": "string", "description": "TPM endorsement key." }, "storageRootKey": { "type": "string", "description": "TPM storage root key." } }, "required": [ "endorsementKey" ] }, "TpmRegistrationResult": { "type": "object", "description": "TPM registration result.", "properties": { "authenticationKey": { "type": "string", "description": "Encrypted authentication key." } } }, "X509CertificateInfo": { "type": "object", "description": "X509 certificate info.", "properties": { "subjectName": { "type": "string", "description": "Certificate subject name." }, "sha1Thumbprint": { "type": "string", "description": "SHA-1 thumbprint of the certificate." }, "sha256Thumbprint": { "type": "string", "description": "SHA-256 thumbprint of the certificate." }, "issuerName": { "type": "string", "description": "Certificate issuer name." }, "notBeforeUtc": { "type": "string", "format": "date-time", "description": "Certificate validity start date (UTC)." }, "notAfterUtc": { "type": "string", "format": "date-time", "description": "Certificate expiry date (UTC)." }, "serialNumber": { "type": "string", "description": "Certificate serial number." }, "version": { "type": "integer", "format": "int32", "description": "Certificate version." } }, "required": [ "subjectName", "sha1Thumbprint", "sha256Thumbprint", "issuerName", "notBeforeUtc", "notAfterUtc", "serialNumber", "version" ] }, "X509RegistrationResult": { "type": "object", "description": "X509 registration result.", "properties": { "certificateInfo": { "$ref": "#/definitions/X509CertificateInfo", "description": "X509 certificate info." }, "enrollmentGroupId": { "type": "string", "description": "Enrollment group ID." }, "signingCertificateInfo": { "$ref": "#/definitions/X509CertificateInfo", "description": "X509 certificate info." } } } }, "parameters": { "Azure.Core.Foundations.ApiVersionParameter": { "name": "api-version", "in": "query", "description": "The API version to use for this operation.", "required": true, "type": "string", "minLength": 1, "x-ms-parameter-location": "method", "x-ms-client-name": "apiVersion" } } }