Connect an IoT Device

Use this guide to connect a device when your integration is managed through the Infuse IoT API rather than a dashboard UI.

Before you start, keep your Infuse IoT admin credential on a trusted backend. Current Infuse IoT 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.

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.

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

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 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 Telemetry and State to track state, routes, logger progress, and KV entries.
• Use Commands and RPC for production command flows.
• Use Definitions to align backend payloads with firmware schemas.