canonical: https://jentic.com/apis/azure.com/iotdpsclient

# Microsoft Azure iotDpsClient

Jentic publishes the only available OpenAPI specification for the Azure IoT Hub Device Provisioning Service control plane, keeping it validated and agent-ready. The Microsoft.Devices/provisioningServices resource provider creates and manages DPS instances that handle zero-touch IoT device enrolment into IoT Hubs. It exposes 18 ARM endpoints to provision DPS instances, manage CA certificates, generate and verify proof-of-possession codes, list shared access keys, and check name availability before deploy.

## For AI agents

Provision Azure IoT Device Provisioning Service instances, manage CA certificates and shared access keys, and check provisioning service name availability through Azure Resource Manager.

## Scope

Does not handle individual device enrolment, attestation runtime, or IoT Hub messaging - use for DPS resource and certificate management on the ARM control plane only.

## Capabilities

- Create or update an IoT Device Provisioning Service in a resource group
- List provisioning services across a subscription or filtered by resource group
- Upload and verify a CA certificate via generateVerificationCode and verify operations
- List shared access keys for a provisioning service or a specific key by keyName
- Check whether a candidate provisioning service name is available before deploy
- Poll long-running operations through operationresults/{operationId}

## Use cases

### Zero-Touch Device Onboarding Foundation

Manufacturers stand up a DPS instance per fleet to onboard millions of devices into IoT Hubs without per-device manual configuration. The API drives the full provisioning service lifecycle through ARM, including CA certificate upload and proof-of-possession verification, so device-side X.509 attestation works end-to-end. Setup of a new DPS instance with a verified CA is a one-day exercise.

Example prompt: PUT a new provisioning service named 'acme-dps' in resource group 'rg-iot' linked to IoT Hub 'acme-hub' and return the resource id.

### CA Certificate Lifecycle Automation

Security teams automate CA certificate rotation by uploading the new CA, calling generateVerificationCode, signing the returned nonce with the CA private key, and posting the proof to verify. The API handles the verification handshake natively so rotation can be scripted on a schedule. A rotation cycle takes minutes once the signing tooling is in place.

Example prompt: Upload CA certificate 'newCA' to DPS 'acme-dps', call generateVerificationCode, then POST the signed verification body to the verify endpoint.

### Multi-Region DPS Inventory

Operations teams enumerate every provisioning service across a subscription to track regional spread and feed cost and compliance dashboards. Both subscription-scoped and resource-group-scoped listing endpoints are available, so the inventory can pivot by team or environment. Pull is seconds for typical fleets.

Example prompt: List all provisioningServices in the subscription and emit a CSV with name, resourceGroup, and location.

### Agent-Driven DPS Operations via Jentic

An AI ops agent can stand up a DPS, attach a CA, and rotate keys through Jentic without holding raw Azure AD credentials. The agent searches Jentic for 'create an Azure DPS instance', loads the operation schema, and executes against Microsoft.Devices/provisioningServices. Jentic's your Jentic One instance injects a scoped bearer token for management.azure.com.

Example prompt: Use the Jentic MCP tool azure_dps_create_service to provision DPS 'demo-dps' in resource group 'rg-iot' linked to IoT Hub 'demo-hub'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.Devices/provisioningServices | List provisioning services in the subscription |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/provisioningServices/{provisioningServiceName} | Create or update a provisioning service |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/provisioningServices/{provisioningServiceName}/certificates/{certificateName} | Upload a CA certificate |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/provisioningServices/{provisioningServiceName}/certificates/{certificateName}/generateVerificationCode | Generate a verification code for the certificate |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/provisioningServices/{provisioningServiceName}/certificates/{certificateName}/verify | Submit the signed verification body |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/provisioningServices/{provisioningServiceName}/listkeys | List shared access keys for the provisioning service |
| POST | /subscriptions/{subscriptionId}/providers/Microsoft.Devices/checkProvisioningServiceNameAvailability | Check if a provisioning service name is available |

## Key resources

- **ProvisioningServices** — Top-level DPS resources that route devices to IoT Hubs
- **Certificates** — CA certificates uploaded to a DPS, with verification handshake operations
- **Keys** — Shared access keys used to authorise DPS service operations
- **OperationResults** — Status records for long-running DPS operations
- **NameAvailability** — Pre-flight check for provisioning service name collisions

## Why Jentic

- **Setup:** Wiring the IoT Device Provisioning Service management API by hand means registering an Azure AD app, negotiating OAuth 2.0 tokens for management.azure.com, and threading subscription and resource-group scope through every certificate and provisioning-service call. Through Jentic you install once, import iotDpsClient from the API Directory, store the Azure AD credential once, and your agent calls it.
- **Permission scoping:** This API puts the provisioning service and certificate in the URL path (/provisioningServices/{provisioningServiceName}/certificates/{certificateName}), so a rule can pin your agent to one provisioning service: it can list services and read or verify its certificates. You choose the operations it may call, so listing access keys or replacing a certificate is not included unless you add it.
- **Credential handling:** Your Azure AD credential for the DPS control plane is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list IoT DPS provisioning services' or 'verify a DPS certificate', and Jentic returns the matching DPS operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Azure IoT Hub** — DPS routes devices into IoT Hubs created by the IoT Hub control plane.
- **Azure IoT Central** — IoT Central applications can be the target for DPS-onboarded devices.
- **Azure Key Vault** — Key Vault stores the CA certificate private keys used in DPS proof-of-possession flows.

## FAQ

### Why is there no official OpenAPI spec for iotDpsClient?

Microsoft does not publish a maintained OpenAPI 3 specification for the Microsoft.Devices/provisioningServices control plane. Jentic generates and maintains this spec so that AI agents and developers can call iotDpsClient via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the iotDpsClient use?

It uses Azure Active Directory OAuth 2.0 against management.azure.com with the user_impersonation scope, the standard ARM auth. Through Jentic the AAD client secret is held in the your Jentic One instance and a scoped bearer token is injected per call so the agent never sees raw secrets.

### Can I rotate DPS shared access keys with this API?

You can list keys via .../provisioningServices/{provisioningServiceName}/listkeys and inspect a single key via .../keys/{keyName}/listkeys. To rotate, update the provisioning service resource with a new authorizationPolicies array using PUT on the provisioningServices/{provisioningServiceName} endpoint.

### What are the rate limits for iotDpsClient?

It runs on the Azure Resource Manager plane and inherits ARM throttling - typically 12,000 reads and 1,200 writes per hour per subscription, surfaced via x-ms-ratelimit-remaining-subscription-* headers. The DPS RP itself does not document tighter management-plane limits.

### How do I provision a new DPS through Jentic?

Run pip install jentic, then search Jentic with 'create an Azure DPS instance', load the create-or-update operation, and execute with subscriptionId, resourceGroupName, provisioningServiceName, location, and a properties object that links to the target IoT Hub. Jentic returns the deployed resource.

### Does this API enrol individual devices?

No. This is the management plane that creates and configures DPS instances, certificates, and keys. To create individual enrolment groups and individual enrolments and to register devices, use the DPS service-side API at {service-name}.azure-devices-provisioning.net instead.

### Can I limit what my agent is allowed to do with the Microsoft Azure IoT DPS API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this API puts the provisioning service and certificate in the URL path, so you can pin an agent to a single provisioning service. You choose the exact operations it can call, so you might allow it to list provisioning services and read or verify their certificates while withholding listing shared access keys or replacing a certificate. Your Azure AD credential stays with your Jentic One instance and is injected at execution time, never reaching the agent's prompt or logs.