az iot device registration

  • Preview

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.73.0 or higher). The extension will automatically install the first time you run an az iot device registration command. Learn more about extensions.

This command group is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Register a device through Azure IoT Hub Device Provisioning Service (DPS).

Use create for an individual or group enrollment, then operation-status to follow an accepted registration. Authenticate the device with its symmetric key or an X.509 certificate. Service enrollment records and registration-state administration remain under az iot dps.

Commands

Name Description Type Status
az iot device registration create

Register a device and optionally issue its operational certificate.

 Extension Preview
az iot device registration operation-status

Show the status of a DPS device registration operation.

 Extension Preview

az iot device registration create

Preview

Command group 'iot device registration' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Register a device and optionally issue its operational certificate.

For an individual enrollment, supply its device --symmetric-key. For a group enrollment, supply the group key with --compute-key, or supply an already derived device key without --compute-key. Alternatively, use --dps-name with --auth-type login to discover the ID scope/endpoint and retrieve enrollment keys; add --group-id and --compute-key for a group enrollment. Entra login authorizes this bootstrap lookup, not the device registration request.

Use --id-scope with explicit device credentials to skip DPS resource discovery. Set --host when using a non-default provisioning endpoint. For X.509 authentication, supply --certificate-file-path and --key-file-path; add --passphrase only if the private key is encrypted.

Add --csr (alias --csr-file-path) to request an operational certificate. It accepts PEM or base64 DER PKCS #10, inline or from a file. The CSR signature must be valid and its Common Name must match --registration-id. A CSR does not replace the device's symmetric-key or X.509 authentication.

The command polls accepted registrations, honoring Retry-After. If it times out after receiving an operation ID, use operation-status with that ID and the same registration ID, ID scope, endpoint and device authentication. A timeout does not cancel the backend operation; do not blindly rerun create. --timeout applies a hard deadline to the same REST flow for both CSR and non-CSR registration, including worker startup, HTTP retries and polling, after preliminary ID scope and bootstrap credential discovery. Without --timeout, the existing bounded five-minute polling behavior is retained.

JSON output preserves issuedCertificateChain and connectionProfile when DPS returns them, plus registryDeviceExternalId for Registry Device correlation. The 2026-11-02-preview RegisterDeviceAndIssueCertificate contract describes issuedCertificateChain only as an array of bytes and does not define its wire encoding or certificate order. Consequently, this command preserves that field in JSON output but does not offer a certificate-file output option; writing a guessed chain could produce a non-TLS-ready or incorrectly ordered bundle. --endorsement-key and --storage-root-key are retained as advanced request-schema fields, but TPM-only authentication is explicitly unsupported because this contract provides no client TPM challenge protocol.

az iot device registration create --registration-id --rid
                                  [--acquire-policy-token]
                                  [--auth-type {key, login}]
                                  [--certificate-file-path --cp]
                                  [--change-reference]
                                  [--ck --compute-key]
                                  [--csr --csr-file-path]
                                  [--dps-name]
                                  [--endorsement-key]
                                  [--enrollment-group-id --gid --group-id]
                                  [--host --provisioning-host]
                                  [--id-scope --scope]
                                  [--key --symmetric-key]
                                  [--key-file-path --kp]
                                  [--login]
                                  [--pass --passphrase]
                                  [--payload]
                                  [--resource-group]
                                  [--storage-root-key]
                                  [--timeout]

Examples

Register an individual enrollment using Entra-authorized bootstrap key lookup

az iot device registration create --dps-name MyDps --resource-group MyResourceGroup \
  --registration-id device-01 --auth-type login

Register a group member using Entra-authorized bootstrap key lookup

az iot device registration create --dps-name MyDps --registration-id device-01 \
  --group-id MyEnrollmentGroup --compute-key --auth-type login

Register with a device key and known ID scope, without bootstrap lookup

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --symmetric-key DEVICE_KEY

Derive a device key from an enrollment group key and register

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --symmetric-key GROUP_KEY --compute-key

Register and request an operational certificate from a PEM CSR

az iot device registration create --id-scope 0ne00000000 --registration-id device-01 \
  --symmetric-key DEVICE_KEY --csr ./device-01.csr --timeout 120

Register with an X.509 device certificate

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --certificate-file-path ./device.pem \
  --key-file-path ./device-key.pem

Required Parameters

--registration-id --rid

Device registration ID or individual enrollment ID.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--certificate-file-path --cp

Path to certificate PEM file. Required for x509 registrations.

Property Value
Parameter group: x509 Authentication Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--ck --compute-key

Compute the per-device key from --symmetric-key, or from the enrollment-group key resolved by --group-id with --dps-name/--login. Cannot be combined with X.509 inputs.

Property Value
Parameter group: Symmetric Key Authentication Arguments
Default value: False
--csr --csr-file-path

Inline PEM/base64 DER PKCS #10 CSR or path to a CSR file. Its signature must be valid and Common Name must match the registration ID. The request sends base64 DER without PEM headers.

Property Value
Parameter group: Certificate Issuance Arguments
--dps-name -n

Name of the Azure IoT Hub Device Provisioning Service. Required if --login is not provided or authenticaton arguments and --id-scope are not provided.

Property Value
Parameter group: DPS Identifier Arguments
--endorsement-key

Advanced TPM request field retained by the service schema. Must be used with --storage-root-key. TPM-only client authentication is not supported by this command.

Property Value
Parameter group: TPM Arguments
--enrollment-group-id --gid --group-id

Enrollment group ID. Only needed to retrieve authentication arguments.

--host --provisioning-host

DPS device endpoint. When omitted, the endpoint is derived from the selected DPS resource, then falls back to the global endpoint.

--id-scope --scope

ID scope of the Azure IoT Hub Device Provisioning Service. ID scope does not identify a device endpoint: --dps-name or --login is still resolved when supplied. With only --id-scope and explicit device credentials, the documented global endpoint fallback is used.

Property Value
Parameter group: DPS Identifier Arguments
--key --symmetric-key

The symmetric shared access key for the device registration.

Property Value
Parameter group: Symmetric Key Authentication Arguments
--key-file-path --kp

Path to key PEM file. Required for x509 registrations.

Property Value
Parameter group: x509 Authentication Arguments
--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --dps-name is not provided or authenticaton arguments and --id-scope are not provided.

Property Value
Parameter group: DPS Identifier Arguments
--pass --passphrase

Passphrase for the X.509 private key. Valid only with both --certificate-file-path and --key-file-path.

Property Value
Parameter group: x509 Authentication Arguments
--payload

Registration payload as a JSON object or path to a JSON file.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--storage-root-key

Advanced TPM request field retained by the service schema. Must be used with --endorsement-key. TPM-only client authentication is not supported by this command.

Property Value
Parameter group: TPM Arguments
--timeout

Positive integer hard REST registration timeout in seconds, including worker startup, HTTP and polling. Excludes preliminary ID scope and bootstrap credential discovery.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot device registration operation-status

Preview

Command group 'iot device registration' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show the status of a DPS device registration operation.

Supply the operation ID returned by DPS or reported by create after a timeout. Reuse the registration ID, ID scope (or DPS name), provisioning host and device authentication from create. This is a status read, not a new registration.

az iot device registration operation-status --operation-id
                                            --registration-id --rid
                                            [--acquire-policy-token]
                                            [--auth-type {key, login}]
                                            [--certificate-file-path --cp]
                                            [--change-reference]
                                            [--ck --compute-key]
                                            [--dps-name]
                                            [--enrollment-group-id --gid --group-id]
                                            [--host --provisioning-host]
                                            [--id-scope --scope]
                                            [--key --symmetric-key]
                                            [--key-file-path --kp]
                                            [--login]
                                            [--pass --passphrase]
                                            [--resource-group]

Examples

Follow an individual enrollment with bootstrap key lookup

az iot device registration operation-status --dps-name MyDps \
  --registration-id device-01 --operation-id OPERATION_ID --auth-type login

Follow a group member with the same group key and provisioning host

az iot device registration operation-status --id-scope 0ne00000000 \
  --registration-id device-01 --operation-id OPERATION_ID \
  --symmetric-key GROUP_KEY --compute-key --host MyProvisioningHost

Follow an accepted operation after a timeout without resubmitting registration

az iot device registration operation-status --id-scope 0ne00000000 \
  --registration-id device-01 --operation-id OPERATION_ID --symmetric-key DEVICE_KEY

Required Parameters

--operation-id

Registration operation identifier returned by create.

--registration-id --rid

Device registration ID or individual enrollment ID.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--certificate-file-path --cp

Path to certificate PEM file. Required for x509 registrations.

Property Value
Parameter group: x509 Authentication Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--ck --compute-key

Compute the per-device key from --symmetric-key, or from the enrollment-group key resolved by --group-id with --dps-name/--login. Cannot be combined with X.509 inputs.

Property Value
Parameter group: Symmetric Key Authentication Arguments
Default value: False
--dps-name -n

Name of the Azure IoT Hub Device Provisioning Service. Required if --login is not provided or authenticaton arguments and --id-scope are not provided.

Property Value
Parameter group: DPS Identifier Arguments
--enrollment-group-id --gid --group-id

Enrollment group ID. Only needed to retrieve authentication arguments.

--host --provisioning-host

DPS device endpoint. When omitted, the endpoint is derived from the selected DPS resource, then falls back to the global endpoint.

--id-scope --scope

ID scope of the Azure IoT Hub Device Provisioning Service. ID scope does not identify a device endpoint: --dps-name or --login is still resolved when supplied. With only --id-scope and explicit device credentials, the documented global endpoint fallback is used.

Property Value
Parameter group: DPS Identifier Arguments
--key --symmetric-key

The symmetric shared access key for the device registration.

Property Value
Parameter group: Symmetric Key Authentication Arguments
--key-file-path --kp

Path to key PEM file. Required for x509 registrations.

Property Value
Parameter group: x509 Authentication Arguments
--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --dps-name is not provided or authenticaton arguments and --id-scope are not provided.

Property Value
Parameter group: DPS Identifier Arguments
--pass --passphrase

Passphrase for the X.509 private key. Valid only with both --certificate-file-path and --key-file-path.

Property Value
Parameter group: x509 Authentication Arguments
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False