IoT Hub endpoints

Note

Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier for your solution.

IoT Hub names

You can find the hostname of the IoT hub that hosts your endpoints in the Azure portal, on your IoT hub's Overview working pane. By default, the DNS name of an IoT hub looks like the following example:

{your iot hub name}.azure-devices.net

List of built-in IoT Hub endpoints

Azure IoT Hub is a multi-tenant service that exposes its functionality to various actors. The following diagram shows the various endpoints that IoT Hub exposes.

Diagram showing the list of build-in IoT Hub endpoints.

The following list describes the endpoints:

  • Resource provider. The IoT Hub resource provider exposes an Azure Resource Manager interface. This interface enables Azure subscription owners to create and delete IoT hubs, and to update IoT hub properties. IoT Hub properties govern hub-level shared access policies, as opposed to device-level access control, and functional options for cloud-to-device and device-to-cloud messaging. The IoT Hub resource provider also enables you to export device identities.

  • Device identity management. Each IoT hub exposes a set of HTTPS REST endpoints to manage device identities (create, retrieve, update, and delete). Device identities are used for device authentication and access control.

  • Device twin management. Each IoT hub exposes a set of service-facing HTTPS REST endpoint to query and update device twins (update tags and properties).

  • Jobs management. Each IoT hub exposes a set of service-facing HTTPS REST endpoint to query and manage jobs.

  • Device endpoints. For each device in the identity registry, IoT Hub exposes a set of endpoints. Except where noted, these endpoints are exposed using MQTT v3.1.1, HTTPS 1.1, and AMQP 1.0 protocols. AMQP and MQTT are also available over WebSockets on port 443.

    • Send device-to-cloud messages. A device uses this endpoint to send device-to-cloud messages.

    • Receive cloud-to-device messages. A device uses this endpoint to receive targeted cloud-to-device messages.

    • Initiate file uploads. A device uses this endpoint to receive an Azure Storage SAS URI from IoT Hub to upload a file.

    • Retrieve and update device twin properties. A device uses this endpoint to access its device twin's properties. HTTPS isn't supported.

    • Receive direct method requests. A device uses this endpoint to listen for direct method requests. HTTPS isn't supported.

    Important

    The following functionality for devices that use X.509 certificate authority (CA) authentication is not yet generally available, and preview mode must be enabled:

    • HTTPS, MQTT over WebSockets, and AMQP over WebSockets protocols.
    • File uploads (all protocols).

    These features are generally available on devices that use X.509 thumbprint authentication. To learn more about X.509 authentication with IoT Hub, see Supported X.509 certificates.

  • Service endpoints. Each IoT hub exposes a set of endpoints for your solution back end to communicate with your devices. With one exception, these endpoints are only exposed using the AMQP and AMQP over WebSockets protocols. The direct method invocation endpoint is exposed over the HTTPS protocol.

    • Receive device-to-cloud messages. This endpoint is compatible with Azure Event Hubs. A back-end service can use it to read the device-to-cloud messages sent by your devices. You can create custom endpoints on your IoT hub in addition to this built-in endpoint.

    • Send cloud-to-device messages and receive delivery acknowledgments. These endpoints enable your solution back end to send reliable cloud-to-device messages, and to receive the corresponding delivery or expiration acknowledgments.

    • Receive file notifications. This messaging endpoint allows you to receive notifications of when your devices successfully upload a file.

    • Direct method invocation. This endpoint allows a back-end service to invoke a direct method on a device.

The Azure IoT Hub SDKs article describes the various ways to access these endpoints.

All IoT Hub endpoints use the TLS protocol, and no endpoint is ever exposed on unencrypted/unsecured channels.

Custom endpoints

You can link existing Azure services in your Azure subscriptions to your IoT hub to act as endpoints for message routing. These endpoints act as service endpoints and are used as sinks for message routes. Devices can't write directly to these endpoints. For more information about message routing, see Use IoT Hub message routing to send device-to-cloud messages to different endpoints.

IoT Hub currently supports the following Azure services as custom endpoints:

  • Storage containers
  • Event Hubs
  • Service Bus Queues
  • Service Bus Topics
  • Cosmos DB (preview)

For the limits on the number of endpoints you can add, see Quotas and throttling.

Endpoint Health

You can use the REST API Get Endpoint Health to get health status of the endpoints. We recommend using the IoT Hub routing metrics related to routing message latency to identify and debug errors when endpoint health is dead or unhealthy, as we expect latency to be higher when the endpoint is in one of those states. To learn more about using IoT Hub metrics, see Monitor IoT Hub.

Health Status Description
healthy The endpoint is accepting messages as expected.
unhealthy The endpoint is not accepting messages and IoT Hub is retrying to send messages to this endpoint.
unknown IoT Hub has not attempted to deliver messages to this endpoint.
degraded The endpoint is accepting messages slower than expected or is recovering from an unhealthy state.
dead IoT Hub is no longer delivering messages to this endpoint. Retries to send messages to this endpoint failed.

Field gateways

In an IoT solution, a field gateway sits between your devices and your IoT Hub endpoints. It's typically located close to your devices. Your devices communicate directly with the field gateway by using a protocol supported by the devices. The field gateway connects to an IoT Hub endpoint using a protocol that is supported by IoT Hub. A field gateway might be a dedicated hardware device or a low-power computer running custom gateway software.

You can use Azure IoT Edge to implement a field gateway. IoT Edge offers functionality such as multiplexing communications from multiple devices onto the same IoT Hub connection.

Next steps

Other reference topics in this IoT Hub developer guide include: