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

# Microsoft Azure iotHubClient

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.

## For AI agents

Provision Azure IoT Hubs, manage CA certificates and shared access keys, configure and test message routing, and trigger failover via Azure Resource Manager.

## Scope

Does not handle device-to-cloud messaging, device twin operations, or direct method invocation - use for IoT Hub control-plane management only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **IotHubs** — Top-level IoT Hub resources with full create, update, and delete lifecycle
- **IotHubKeys** — Shared access keys used by services and devices to authenticate against the hub
- **Certificates** — CA certificates uploaded to the hub with verification handshake operations
- **Routing** — Message routing rules and dry-run validation paths ($testall, $testnew)
- **RoutingEndpointsHealth** — Per-endpoint health for routed message destinations
- **Failover** — Manual failover operation that promotes the paired region
- **Usages** — Subscription-scoped quota and consumption counters

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **Azure IoT Device Provisioning Service** — DPS routes devices into IoT Hubs created by this API.
- **Azure IoT Central** — IoT Central is a SaaS app shell over IoT Hub for users who want a UI rather than raw hub management.
- **Azure Key Vault** — Key Vault stores the connection strings and CA private keys used by IoT Hub workloads.

## FAQ

### 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.