Microsoft Azure iotHubClient
Browse all Azure APIs★ Only Publicly Available OpenAPI DocumentIOTDevice Managementoauth232 EndpointsREST
For Agents
Provision Azure IoT Hubs, manage CA certificates and shared access keys, configure and test message routing, and trigger failover via Azure Resource Manager.
Use for: I need to provision a new Azure IoT Hub, List all IoT Hubs in my subscription, Test a new routing rule before saving it, Trigger a failover for my IoT Hub to its paired region
Not supported: Does not handle device-to-cloud messaging, device twin operations, or direct method invocation - use for IoT Hub control-plane management only.
Jentic publishes the only available OpenAPI specification for the Azure IoT Hub control plane (2019-07-01-preview), keeping it validated and agent-ready. The Microsoft.Devices/IotHubs resource provider creates and manages IoT Hub instances, their CA certificates, shared access keys, message routing, failover behaviour, and quota usage. It exposes 32 ARM endpoints to provision hubs, manage routing rules with $testall and $testnew dry-run paths, check routing endpoint health, list quota usage, and trigger manual failover.
Install Jentic One Beta
Connect the iotHubClient to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the iotHubClient, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fazure.com%2Fiothubclient" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fazure.com%2Fiothubclient" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with iotHubClient API.
Create or update an Azure IoT Hub in a resource group
Manage CA certificates with verification code generation and verify operations
List shared access keys for an IoT Hub or a single key by keyName
Test routing rules with $testall and $testnew before saving them
Inspect routing endpoint health and IoT Hub stats and usage quotas
Trigger a manual failover of an IoT Hub to its paired region
Check whether a candidate IoT Hub name is available before deploy
Use Cases
Patterns agents use iotHubClient API for, with concrete tasks.
★ Standing Up a New IoT Hub Region
Platform teams provision IoT Hubs in new regions by checking name availability, creating the hub with the desired sku and capacity, and listing keys to seed downstream services. The API drives the full lifecycle through ARM, so a Terraform-style script can stand up a region in minutes once quotas are in place.
Check name availability for 'acme-eus2-hub', then PUT a new IoT Hub in resource group 'rg-iot' using the S1 sku and capacity 2.
Routing Rule Validation Before Deploy
Before saving a new IoT Hub routing rule, operators dry-run it against the existing or candidate route set using the $testall and $testnew paths. This catches misconfigured queries that would otherwise drop messages once activated. The dry-run loop runs in seconds and is the safe default for any routing change.
POST a candidate route with condition "$body.tempC > 80" to the $testnew endpoint on iotHub 'acme-hub' and confirm a positive match against a sample message.
Disaster Recovery Failover Drill
Run periodic disaster recovery drills by calling the failover endpoint on a non-production IoT Hub to confirm the paired region promotes correctly. The API exposes failover as a single POST under /IotHubs/{iotHubName}/failover so the drill is a one-line script. Combined with routingEndpointsHealth checks, this becomes a repeatable resilience test.
POST to /subscriptions/{subscriptionId}/resourceGroups/rg-iot/providers/Microsoft.Devices/IotHubs/dr-test-hub/failover and poll for completion.
Quota and Health Inventory
Operators pull /usages by subscription and /IotHubStats and /routingEndpointsHealth per hub to feed capacity and SLA dashboards. The endpoints surface free capacity, daily message counts, and per-endpoint health so capacity planning is data-driven. Refresh runs in seconds for typical estates.
Get IotHubStats for 'acme-hub' and append the dailyMessageCount to a metrics CSV.
Agent-Driven IoT Hub Operations via Jentic
An AI ops agent can provision hubs, rotate keys, and trigger failover through Jentic without holding Azure AD secrets. The agent searches Jentic for 'create an Azure IoT Hub', loads the operation schema, and executes against Microsoft.Devices/IotHubs. Jentic's your Jentic One instance injects a scoped bearer token for management.azure.com.
Use the Jentic MCP tool azure_iothub_create_hub to provision IoT Hub 'demo-hub' in resource group 'rg-iot' with sku S1 and capacity 1.
Key Endpoints
32 endpoints — jentic publishes the only available openapi specification for the azure iot hub control plane (2019-07-01-preview), keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
GET
/subscriptions/{subscriptionId}/providers/Microsoft.Devices/IotHubs
List IoT Hubs in the subscription
PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}
Create or update an IoT Hub
POST
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/failover
Trigger manual failover to the paired region
POST
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testnew
Test a candidate routing rule
POST
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/IotHubKeys/{keyName}/listkeys
List a single shared access key
PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}
Upload a CA certificate
POST
/subscriptions/{subscriptionId}/providers/Microsoft.Devices/checkNameAvailability
Check if a hub name is available
GET
/subscriptions/{subscriptionId}/providers/Microsoft.Devices/IotHubs
List IoT Hubs in the subscription
PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}
Create or update an IoT Hub
POST
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/failover
Trigger manual failover to the paired region
POST
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testnew
Test a candidate routing rule
POST
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/IotHubKeys/{keyName}/listkeys
List a single shared access key
PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}
Upload a CA certificate
POST
/subscriptions/{subscriptionId}/providers/Microsoft.Devices/checkNameAvailability
Check if a hub name is available
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the IoT Hub management API by hand means registering an Azure AD app, negotiating OAuth 2.0 tokens for management.azure.com, and carrying subscription and resource-group scope through every hub, routing, and key call. Through Jentic you install once, import iotHubClient from the API Directory, store the Azure AD credential once, and your agent calls it.
Permission scoping
This API puts the hub in the URL path (/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/...), so a rule can pin your agent to one IoT hub: it can read the hub and test its routing rules. You choose the operations it may call, so triggering a manual failover or listing hub keys is not included unless you add it.
Credential isolation
Your Azure AD credential for the IoT Hub 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.
Intent-based discovery
Agents search Jentic by intent such as 'list IoT hubs in a subscription' or 'test an IoT Hub routing rule', and Jentic returns the matching IoT Hub operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using iotHubClient API through Jentic.
Why is there no official OpenAPI spec for iotHubClient?
Microsoft does not publish a maintained OpenAPI 3 specification for the Microsoft.Devices/IotHubs control plane. Jentic generates and maintains this spec so that AI agents and developers can call iotHubClient 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 iotHubClient 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 dry-run a routing rule before saving it?
Yes. POST a candidate route to .../IotHubs/{iotHubName}/routing/routes/$testnew to evaluate a single new rule against a sample message, or to .../$testall to evaluate the full route set. This is the safe way to validate routing changes before deploy.
What are the rate limits for iotHubClient?
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 IoT Hub RP itself does not document tighter management-plane limits.
How do I trigger a hub failover through Jentic?
Run pip install jentic, then search Jentic with 'failover an azure iot hub', load the failover operation, and execute with subscriptionId, resourceGroupName, and iotHubName. Jentic returns the operation handle so you can poll completion.
Does this API send messages to or from devices?
No. This is the management plane that creates and configures IoT Hub resources. To send cloud-to-device messages, register devices, or read device twins, use the IoT Hub service-side API at {iot-hub-name}.azure-devices.net instead.
Can I limit what my agent is allowed to do with the Azure IoT Hub API?
Yes. Because this API carries the hub in the URL path (/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/...), your own rules in your self-hosted Jentic One instance can pin the agent to a single IoT hub and to a specific set of operations. You decide the allowed calls, so you can grant read-only access and routing dry-runs against $testnew and $testall while withholding riskier operations like triggering a manual failover or listing shared access keys unless you explicitly add them. The Azure AD credential is held by your Jentic One instance and injected at execution time, so the agent only ever reaches the endpoints you permit.
GET STARTED