Use your IoT Hub securely
Goal: Pick the right key for what you are building, and keep it where only that thing can read it.
A data connection is one device in an Azure IoT Hub. The hub works the normal way: keys are how it admits a caller, and using them is part of the feature. What makes a key safe is who holds it. This page goes through the things you might build on your connection, one section each: the key that thing holds, where to keep it, and what it never holds.
| You are building | It holds | Keep it in | Never use |
|---|---|---|---|
| A device in the field | Its own device key | The device | A key for the whole hub |
| A run of units | One device key per unit | Each unit, and one copy in your secret store | One key shared by the units |
| A gateway | The keys of the devices it speaks for | The gateway's secret store | A key for the whole hub |
| Your own back-end service | The narrowest hub policy, or a Microsoft sign-in | Key Vault, or a workbench's Environment tab | iothubowner |
| A page, an app or a partner system | No key | Nowhere: it calls a relay workbench or the workspace API | Any key in code it ships |
| An AI | No key | Nowhere: a workbench it calls holds the key | A key pasted into a chat |
The hub is yours to use
Your devices connect to the hub from wherever they are, so the hub is reachable from any network. Who gets in is decided by keys, and there are two kinds:
| A device key | A hub policy key | |
|---|---|---|
| What it opens | One device: it sends that device's messages and nothing else | What its policy allows, across every device in the hub |
| Where you get it | Inspector -> Connection Info -> Device ConnStr (primary) for the connection, shown to people who can deploy | Azure, on a hub you own |
| What a leak costs | One device | Every device the policy reaches |
Hold the narrowest key that does the job. A device holds a device key. Anything that works across devices holds the narrowest hub policy, or signs in with Microsoft instead of holding a key. Connection Info shows a device's own values (Live Devices), not a policy key for the whole hub.
On Fathym's shared hub you hold device keys only: the hub's policies stay with Fathym. Once your workspace has its own fabric, the hub is in your own Azure subscription and its policies are yours.
A device in the field
A device holds its own key-based connection string, and nothing else for the hub:
HostName=<hub>.azure-devices.net;DeviceId=<device id>;SharedAccessKey=<device key>
- It holds its own device key. It makes its own short-lived pass from the key each time it connects, and an Azure IoT device SDK does that for you. Firmware without an SDK follows Mint the pass from the key; Point the device at it shows the settings.
- Keep it in the device, written once when you flash it. A device that can hold its key in a SIM or a secure element should; Pilot Devices says where that stands.
- Never give it a key for the whole hub, or a testing token from Connection Info (testing tokens say why).
A run of units
Each unit is its own data connection with its own key. One unit's key opens that unit and nothing else.
- It holds the key of its own connection, written once at flashing.
- Keep the only other copy in your secret store, never in source control, a spreadsheet or a log.
- Never flash a run of units with one shared key: a single leak then forces you to change every unit.
The steps are in One key per unit, and Device Makers covers a maker's side of a run.
A gateway
A gateway in front of many sensors sends on their behalf.
- It holds the keys of the devices it speaks for, and only those. Give each device behind it its own data connection, so each keeps its own key and can be switched off on its own.
- Keep them in the gateway's secret store.
- Never give it a key for the whole hub so that it can send for any device. If the gateway has to add or remove devices, that is a back-end job: give that job its own narrow policy, as in the next section.
Your own back-end service
A service you run on your own fabric's hub, one that sends messages to devices, reads the registry or adds and removes devices, holds the narrowest policy that does that job, or signs in with Microsoft Entra and the matching IoT Hub role. Use this table in place of the all-powerful policy:
| You want to | Use a hub policy | Or sign in with the role | Never use |
|---|---|---|---|
| Send to devices, or read their messages | service | IoT Hub Data Contributor | iothubowner |
| Read the device registry | registryRead | IoT Hub Data Reader | iothubowner |
| Add or remove devices | registryReadWrite | IoT Hub Registry Contributor | iothubowner |
A hub policy key has this shape, and the key is a placeholder:
HostName=<hub>.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=<service key>
- Keep it in a secret store: Azure Key Vault, or the Environment tab of a workbench, whose values become container secrets (Host Your Own Workbench). Never in source control.
- Rotate by moving the service to the policy's secondary key, then regenerating the primary in Azure. Signing in with Microsoft holds no key to rotate.
- On Fathym's shared hub there is no policy to hold. Build a relay workbench, or call the workspace's API (Call from Your App).
A page, an app or a partner system
Code that reaches a visitor's browser or phone, or a service run by someone else, holds no hub key and no device key. Anything shipped to a visitor can be read by the visitor.
- It holds no key. It signs in to OpenX and calls either a relay workbench that sends on one device's behalf, or the workspace's own API.
- Keep the key in the relay: Build a relay workbench shows a workbench that holds one device's key as a secret, checks each caller itself, and sends the caller's message to the hub. You can switch one caller off without touching the device.
- Never put a key in a page, a mobile app, a script tag or a repository a partner can read.
An AI
An AI never holds a key.
- It holds nothing for the hub. It can read a connection's health and your records through OpenX, which needs no key.
- Keep the key in a workbench the AI calls (Reach a Workbench over MCP): the workbench holds the key and the AI holds none.
- Never paste a key into a chat, a prompt or a file you hand to an AI. What goes into a conversation stays in its record.
A shared fabric
On a fabric several workspaces share, the hub, its devices and its keys are shared: every workspace on it reaches the same hub and the same devices. Keep that in mind when you decide who may hold a key: a hub policy key reaches every device on the hub, whichever workspace owns the device. Data & IoT Fabric describes the fabric.
If a key is exposed
Switch the connection off in its Inspector and Deploy. The device is disabled in the hub, so it cannot send, while you change the key. How to change a device's key is in Replace a credential. A hub policy key on a hub you own is regenerated in Azure: move your services to the secondary key first, then regenerate the primary.