Device Role Assignment

When you create a device, it only has limited roles to read its own details. You need to assign roles to allow the device to perform additional operations using its token.

The following section shows how to assign roles to devices:

What you can do

• Assign a role to a device
• Replace roles assigned to a device
• Remove a role from a device
• List all roles assigned to a device

Before you start, make sure:

1. The device exists
2. The device is associated to the account or group on which you want to assign the role
3. You have permission to assign roles
4. The role you want to assign exists

API Endpoints

Assign a role to a device

You can assign roles to devices on account and group using the POST roles API spec

Parameters:

• deviceId - ID of your device

• roleId - ID of the role you want to assign

• entityTrn - Account or group on which you want to assign the role to the device. If ‘on’ is not provided, it defaults to caller’s account

Example Request:

curl -X POST \
  "{BaseUrl}/devices/{deviceId}/roles/{roleId}?on={entityTrn}" \
  -H "Authorization: Bearer {token}"

Success Response (201):

{
  "id": "device-uuid",
  "trn": "trn:2:iam:<region>:device:<device_id>",
  "metadata": {
    "createdBy": "trn:2:iam:us:user/application/device:00000000-0000-0000-0000-000000000000",
    "createdAt": "2024-07-29T00:00:00.000Z",
    "updatedBy": "trn:2:iam:us:user/application/device:00000000-0000-0000-0000-000000000000",
    "updatedAt": "2024-07-29T00:00:00.000Z"
  }
}

Replace device roles

Replace the calling application’s roles on an existing device-entity relation using the PUT roles API spec

This operation does not create a new relation. The device must already be associated with the target account or group. Role IDs belonging to other applications on the same relation are preserved.

Parameters:

• deviceId - ID of your device

• on - Account or group TRN on which to replace the device’s roles. If on is not provided, it defaults to the caller’s account. Application TRN is not supported (ROL_041)

• roleIds - Required list of role IDs to assign for the calling application. Empty or missing roleIds returns 400 (ROL_110). Owner roles are rejected (ROL_105)

Example Request:

curl -X PUT \
  "{BaseUrl}/devices/{deviceId}/roles?on={entityTrn}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"roleIds": ["{roleId}"]}'

Success Response (200):

{
  "id": "device-uuid",
  "trn": "trn:2:iam:<region>:device:<device_id>",
  "roleIds": [
    "role-uuid"
  ],
  "metadata": {
    "createdBy": "trn:2:iam:us:user/application/device:00000000-0000-0000-0000-000000000000",
    "createdAt": "2024-07-29T00:00:00.000Z",
    "updatedBy": "trn:2:iam:us:user/application/device:00000000-0000-0000-0000-000000000000",
    "updatedAt": "2024-07-29T00:00:00.000Z"
  }
}

Error responses:

• 400 (ROL_041) - Application TRN is not supported in on
• 400 (ROL_105) - Owner role cannot be assigned to devices
• 400 (ROL_110) - roleIds is missing or empty
• 403 (ROL_107) - Caller is not authorized to assign roles to the device
• 404 (ROL_108) - No relation exists between the device and the target entity

Remove Role from Device

Removes a role assigned to device using the DELETE roles API spec

The on parameter is optional - if not provided, it defaults to the caller’s account.

Example Request:

curl -X DELETE \
  "{BaseUrl}/devices/{deviceId}/roles/{roleId}?on={entityTrn}" \
  -H "Authorization: Bearer {token}"

Success Response (204): No content

List Device Roles

List all roles assigned to a device, with optional filtering using the GET roles API spec

Parameters:

• deviceId - ID of your device

• on - Account or group on which to list the device’s roles. If ‘on’ is not provided, it defaults to caller’s account

• scopedToApplicationId - Filter by application. If not provided, it defaults to caller’s application

Example Request:

curl -X GET \
  "{BaseUrl}/devices/{deviceId}/roles?on={entityTrn}&scopedToApplicationId={applicationId}" \
  -H "Authorization: Bearer {token}"

Success Response (200):

[
  {
    "id": "uuid",
    "name": "string",
    "permissionList": [
      {
        "id": "uuid",
        "trn": "string",
        "action": "string",
        "resource": "string",
        "description": "string"
      }
    ]
  }
]

Authorization

Roles can be assigned to device by an application, user or device.

Requirements

• Caller must be authorized to assign roles on the target entity
• Role assignment depends on role ownership:
  • Subject-owned roles (see Role Management): If caller’s application owns the role, it can be assigned directly
  • Shared roles (see Role Sharing): If caller’s application doesn’t own the role, the role must be shared through a common group between the role owner and caller’s application