> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure IoT Hub

> Client-mode REST API connector for a curated Azure IoT Hub slice: registry GetDevice, device-to-cloud SendDeviceEvent, twin GET/PATCH, and InvokeDeviceMethod

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [Azure IoT Hub](https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-overview) covering registry, device-to-cloud events, device twin, and direct methods:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| Registry get (smoke) | `GET /devices/{deviceId}?api-version=…` | Service SAS or Entra |
| POST devices/\{id}/messages/events | `POST /devices/{deviceId}/messages/events?api-version=…` | DeviceConnect SAS; HTTP 204 |
| GET twins/\{id} | `GET /twins/{deviceId}?api-version=…` | Read twin |
| PATCH twins/\{id} | `PATCH /twins/{deviceId}?api-version=…` | Service desired/tags (catalog named reported) |
| POST twins/\{id}/methods | `POST /twins/{deviceId}/methods?api-version=…` | Direct method / command to device |

Default `BASE_ADDRESS` is `https://YOUR_HUB.azure-devices.net` (no trailing slash). Topics use `cloud-iot/azure-iot-hub/<object>/<verb>`. Default `api-version` is **`2021-04-12`**.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** pass `Authorization` as `{value.json.authorization}` — either `SharedAccessSignature sr=…&sig=…&se=…&skn=…` or `Bearer {entra_token}` for **service** APIs. Prefer Hub secrets — never commit real keys into the `.lot`.

> [!NOTE]
>
> **Device SendDeviceEvent** requires a **DeviceConnect** SAS scoped to the device. Microsoft Entra ID is **not** supported for IoT Hub device APIs.

> [!NOTE]
>
> **Event Grid** device events are docs-only / future `ENABLE_SERVER`. This package is client-mode only. Prefer Hub secrets for SAS / Entra. This template has not been verified against a live IoT Hub. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Azure IoT Hub curated slice
# Auth: Authorization → {value.json.authorization}
#   SharedAccessSignature …  OR  Bearer {entra_token} (service)
# BASE_ADDRESS: https://YOUR_HUB.azure-devices.net

DEFINE ROUTE AzureIotHubRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_HUB.azure-devices.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/devices/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/devices/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/devices/{value.json.device_id}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT SendDeviceEvent
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/messages/events/post"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/messages/events/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/devices/{value.json.device_id}/messages/events?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT GetTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/twins/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/twins/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/twins/{value.json.device_id}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT UpdateTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/twins/update"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/twins/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/twins/{value.json.device_id}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "If-Match" "{value.json.if_match}"
        WITH BODY "{payload}"
    ADD EVENT InvokeDeviceMethod
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/twins/methods/post"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/twins/methods/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/twins/{value.json.device_id}/methods?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
```

## MQTT examples

**GetDevice smoke** (`cloud-iot/azure-iot-hub/devices/get`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net&sig=...&se=...&skn=registryRead"
}
```

**SendDeviceEvent** (`cloud-iot/azure-iot-hub/messages/events/post`) — device SAS; expect **204**:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net%2Fdevices%2Fline-a-gw&sig=...&se=...&skn=device",
  "payload": "{\"temp\":72.5}"
}
```

**UpdateTwin** (`cloud-iot/azure-iot-hub/twins/update`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net&sig=...&se=...&skn=service",
  "if_match": "*",
  "payload": "{\"properties\":{\"desired\":{\"pump\":true}}}"
}
```

**InvokeDeviceMethod** (`cloud-iot/azure-iot-hub/twins/methods/post`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net&sig=...&se=...&skn=service",
  "payload": "{\"methodName\":\"reboot\",\"responseTimeoutInSeconds\":30,\"payload\":{}}"
}
```

## Notes

* Replace `YOUR_HUB` in `BASE_ADDRESS` before deploy.
* `api-version=2021-04-12` is required on every request (pass `api_version` in MQTT JSON).
* Service twin PATCH updates **desired** properties and **tags**. Catalog wording said “reported”; reported properties are typically updated by the device.
* Event Grid inbound webhooks are not packaged (future server connector).
* Suggested branches: `feat/rest-api-route-azure-iot-hub`, `feat/docs-rest-api-azure-iot-hub` (Hugo pushes).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Microsoft IoT Hub REST](https://learn.microsoft.com/en-us/rest/api/iothub/)
* [Control access with SAS](https://learn.microsoft.com/en-us/azure/iot-hub/authenticate-authorize-sas)
* [Control access with Entra ID](https://learn.microsoft.com/en-us/azure/iot-hub/authenticate-authorize-azure-ad)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.