Connect an IoT Device

Use this guide when device onboarding is managed by a trusted backend, manufacturing system, gateway, or commissioning tool.

The Infuse console can create boards and networks, generate MQTT tokens, inspect devices, edit metadata, queue KV updates, and dispatch commands. Production device creation and key derivation still usually belong in an API-led workflow because credentials and provisioning material must stay server-side.

Run these calls from a trusted backend. Requests go to the Infuse-IoT Cloud API at https://api.infuse-iot.com.

1. Get An Infuse IoT Token

Create a service account for the onboarding system in the organisation that will own the devices. Give it the IoT access this guide needs: creating boards, networks, and devices, deriving device keys, generating MQTT tokens, and sending RPCs. The IoT Admin template covers all of these; clone it into a narrower organisation role if your workflow does not need everything. Grant these permissions organisation-wide, because the Infuse-IoT Cloud API does not yet support resource-limited IoT grants.

Issue an API key for the service account, then exchange it for an Infuse IoT token:

POST https://api.infuse-cloud.io/iam/auth/token
Content-Type: application/json

{
  "apiKey": "ik_<keyId>.<keySecret>",
  "audience": "infuse-iot"
}

Use the returned accessToken as {infuse_iot_token} in the requests below, and exchange the key again before expiresAt. See Token Exchange for token lifetime and retry guidance.

2. Confirm The Organisation

Devices, boards, networks, and MQTT tokens belong to the organisation that owns the API key. Copy its organisation ID from Organisation settings > Developer tools in the Infuse Portal. The ID is the same in Infuse Platform and Infuse-IoT Cloud.

Creating an organisation in the Infuse Portal also creates its linked Infuse-IoT Cloud organisation, so you do not need to create one with the API. To confirm the organisation from your backend:

GET /organisation/id/{organisationId}
Authorization: Bearer {infuse_iot_token}

Store the organisation ID. You will use it when creating boards, devices, and MQTT tokens.

3. Create Or Select A Board

Boards represent hardware or product profiles.

You can create boards from Infuse IoT > Boards when setting up manually. Use the API when your onboarding system needs to create or reconcile boards automatically.

GET /board?organisationId={organisationId}
Authorization: Bearer {infuse_iot_token}

Create a board if the target hardware profile is not registered:

POST /board
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "organisationId": "{organisationId}",
  "name": "Example Sensor Board",
  "description": "Low-power field sensor board",
  "soc": "nRF9151"
}

Store the returned boardId. Use board metadata fields if your integration needs consistent serial, site, customer, or hardware-variant values.

4. Create Or Select A Network

If your deployment model uses networks, resolve or create the network before registering devices.

You can create networks from Infuse IoT > Networks when setting up manually. Use the API when deployment automation owns network setup.

GET /network?organisationId={organisationId}&includePublic=false
Authorization: Bearer {infuse_iot_token}

POST /network
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "organisationId": "{organisationId}",
  "name": "Field Network",
  "description": "Primary field deployment network",
  "key": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=",
  "public": false,
  "networkId": 1001
}

If your integration does not separate devices by network, keep this step as an internal no-op and continue with the organisation and board identifiers.

5. Create The Device

Create the device with the MCU identifier, board, organisation, and any metadata your backend needs for reconciliation.

POST /device
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "mcuId": "0011223344556677",
  "boardId": "{boardId}",
  "organisationId": "{organisationId}",
  "metadata": {
    "serialNumber": "SN-10001",
    "deploymentSite": "Brisbane"
  }
}

Store the returned deviceId. This is the identifier downstream systems should use for device-specific workflows such as Infuse-Marketplace checkout, RPC commands, and data ingestion.

6. Provision Keys

Fetch the current cloud public key:

GET /key/publicKey
Authorization: Bearer {infuse_iot_token}

Use the device public key to generate shared secret material:

POST /key/sharedSecret
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "key": "{device_public_key_base64}"
}

Derive device encryption key material as required by your provisioning flow:

POST /key/derived/device
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "deviceId": "{deviceId}",
  "interface": "udp"
}

Keep provisioning secrets in your trusted backend, manufacturing system, or device secure storage. Rotate device-specific credentials when devices are replaced, reassigned, or exposed.

7. Generate An MQTT Token

Issue a short-lived MQTT token for the organisation when your device, gateway, or broker integration needs MQTT connectivity.

For development or operational use, you can generate an MQTT token from Infuse IoT > API Access. Backend integrations should generate tokens server-side.

POST /mqtt/token
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "organisationId": "{organisationId}",
  "ttlSeconds": 3600
}

Use the returned expiresAt value to refresh the token before it expires.

8. Confirm Communication

After the device or gateway starts communicating, confirm Infuse-IoT Cloud can see its operational state.

GET /device/deviceId/{deviceId}/state
Authorization: Bearer {infuse_iot_token}

Check the last route when you need to confirm downlink reachability:

GET /device/deviceId/{deviceId}/lastRoute
Authorization: Bearer {infuse_iot_token}

9. Send A Test RPC

Send a small RPC supported by the device firmware.

POST /rpc
Authorization: Bearer {infuse_iot_token}
Content-Type: application/json

{
  "deviceId": "{deviceId}",
  "sendWaitTimeoutMs": 60000,
  "rpc": {
    "commandName": "ping",
    "params": {}
  }
}

Store the returned RPC message ID and read it until the command reaches a terminal state:

GET /rpc/{id}
Authorization: Bearer {infuse_iot_token}

Next Steps

• Use Devices to understand identifiers and lookup paths.
• Use Console to understand the UI workflow.
• Use Boards and Networks to understand setup resources.
• Use Telemetry and State to track state, routes, logger progress, and KV entries.
• Use Device Configuration for metadata, KV updates, and logger sync.
• Use Commands and RPC for production command flows.
• Use Definitions to align backend payloads with firmware schemas.