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.

Before you start, keep your Infuse-IoT Cloud admin credential on a trusted backend. Current Infuse-IoT Cloud API flows use the legacy organisation-level token noted in API Tokens.

1. Identify The Organisation

Find the organisation that should own the device.

GET /organisation/name/{name}
Authorization: Bearer {infuse_iot_admin_token}

If the organisation does not exist in the IoT environment yet, create it:

POST /organisation
Authorization: Bearer {infuse_iot_admin_token}
Content-Type: application/json

{
  "name": "Example Provider"
}

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

2. 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_admin_token}

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

POST /board
Authorization: Bearer {infuse_iot_admin_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.

3. 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_admin_token}

POST /network
Authorization: Bearer {infuse_iot_admin_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.

4. 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_admin_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.

5. Provision Keys

Fetch the current cloud public key:

GET /key/publicKey
Authorization: Bearer {infuse_iot_admin_token}

Use the device public key to generate shared secret material:

POST /key/sharedSecret
Authorization: Bearer {infuse_iot_admin_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_admin_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.

6. 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 a token from Infuse IoT > API Access. Backend integrations should generate tokens server-side.

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

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

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

7. 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_admin_token}

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

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

8. Send A Test RPC

Send a small RPC supported by the device firmware.

POST /rpc
Authorization: Bearer {infuse_iot_admin_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_admin_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.