Skip to content
Identity and Access Management

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
  • 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:

Terminal window
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"
  }
}

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:

Terminal window
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:

Terminal window
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