Device-Group Association

Devices can be associated to one or more groups. This is an optional step that will help manage devices as a collection.

Authorization

Subjects can access resources across different accounts through group memberships.

Use Cases

Applications that created devices want to read the devices after those have been transferred to a Dealer/Customer account
Devices that require communication with Trimble IoT(bidirectional communication with AWS/Azure) need a group association

Device-Group association can be created in two ways:

Option 1

Create group using the POST Groups API spec

Example Request:

POST {base URL}/groups

Request Body

{
    "name": "AlphaGroup"
}

Success Response (201):

{
    "metadata": {
        "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "createdAt": "2025-04-23T18:58:50.008000Z",
        "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "updatedAt": "2025-04-23T18:58:50.008000Z"
    },
    "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "trn": "trn:2:iam:us:group:3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "name": "AlphaGroup"
}

Create device using the POST device API spec

Associate device to group using the POST add device to group API spec

Example Request:

POST {base URL}/groups/{groupId}/devices

Request Body

{
    "id": "{deviceId}"
}

Success Response (201):

{
    "metadata": {
        "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "createdAt": "2025-04-23T18:58:50.008000Z",
        "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "updatedAt": "2025-04-23T18:58:50.008000Z"
    },
    "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "trn": "trn:2:iam:us:group:3a10a36e-12ea-4c98-aa57-3e970bcea56c"
}

Option 2:

Create group using the POST Groups API spec

Example Request:

POST {base URL}/groups

Request Body

{
    "name": "AlphaGroup"
}

Success Response (201):

{
    "metadata": {
        "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "createdAt": "2025-04-23T18:58:50.008000Z",
        "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "updatedAt": "2025-04-23T18:58:50.008000Z"
    },
    "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "trn": "trn:2:iam:us:group:3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "name": "AlphaGroup"
}

Pass the groupId query parameter while creating the device using POST device API spec

Example Request:

POST {base URL}/devices?groupId=3a10a36e-12ea-4c98-aa57-3e970bcea56c

Request Body

{
    "serialNumber": "12345",
    "model": "Tablet",
    "manufacturer":"Trimble",
    "sku": "1342AM2"
}

Success Response (201):

{
    "metadata": {
        "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "createdAt": "2025-04-23T18:58:50.008000Z",
        "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
        "updatedAt": "2025-04-23T18:58:50.008000Z"
    },
    "serialNumber": "12345",
    "manufacturer": "Trimble",
    "model": "Tablet",
    "sku": "1342AM2",
    "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "trn": "trn:2:iam:us:device:3a10a36e-12ea-4c98-aa57-3e970bcea56c"
}