Documentation

Mistake on this page? Email us

Managing devices in your account

You can manage the lifecycle of your devices in Device Directory, including suspending (blocking) and resuming (enabling) devices.

Granting secure device access

With Secure Device Access (SDA), you can give specific users permissions to access and control your deployed IoT devices. Authorized users can connect to IoT devices using the SDA application after they receive authorization from Device Management.

For more information, please see Secure Device Access.

In Portal: Granting secure device access

To grant secure device access to devices:

  1. Select the devices you want to grant secure access to, either:
    • Tick the checkbox next to each ID you want to grant secure access to.
    • Click Saved filters to use an existing filter, or create a new one. Tick the checkbox next to Device ID to select all devices in the filter.
  2. Click the Actions button.
  3. Select Grant secure access.
  4. New secure device access policy page opens.
  5. Enter a name for the access policy and optionally a description.
  6. Select the number of days you want the access token to be valid.
  7. Select the scope of the access (functions available) using the radio buttons:
    • Full access enables all functions. A function is the operation to perform on the device (originating from the customer client application).
    • Selected functions requires a list of functions, each function on a separate line. You can only have between one and 20 scopes for each access token.
  8. Click one of the radio buttons to select how you want the devices to be identified (Device ID (default), Endpoint name or Custom attributes).
  9. Search for a group or users that need access to the access policy.
  10. Click Finish to complete.

You can do this step by step using the Wizard or fill in all necessary information at once using the Quick create.

Using the API: Granting secure device access

The API for granting secure device access to devices is currently restricted.

Suspending and resuming devices

When you suspend a device, you prevent it from connecting to Device Management. If a device is currently connected, it disconnects when you suspend it. This blocks some API operations, including updates. There is no limit to how long a device can stay suspended.

Suspension is useful when a device is lost, stolen, resold, malfunctioning or compromised.

You can also resume Device Management connection to suspended devices. Any operations blocked by suspension are restored.

Note: The time between reconnection attempts increases exponentially, up to one week; therefore devices might not be able to reconnect immediately when you resume them.

In Portal: Suspending and resuming devices

To suspend (block) a device:

  1. Select devices to suspend, either:

    • Tick the checkbox next to each ID you want to suspend.
    • Click Saved filters to use an existing filter, or create a new one. Tick the checkbox next to Device ID to select all devices in the filter.
  2. Click the Actions button.

  3. Select Suspend. A popup window opens.

  4. Click the Reason dropdown menu to select a reason for suspension. This is a required field. Valid reasons are:

    • Lost or stolen.
    • Recalled.
    • Maintenance.
    • Security breach.
    • Other.
  5. Enter a description.

  6. Click Suspend to confirm the action.

    The device is now suspended. It appears greyed out and struck through in Device directory (<device_ID>).

Alternatively:

  1. Click the ID of the device you want to suspend.
  2. Device details pane opens.
  3. On the Summary tab, click the Suspend button.
  4. Give the reason and description as above.

To resume (enable) a device's connection to Device Management:

  1. To list the suspended devices, click Lifecycle status.
  2. Select Suspended.
  3. To select the suspended devices to resume, either:
    • Tick the checkbox next to each ID to resume their connection.
    • Tick the checkbox next to Device ID to select all devices in the filter.
  4. Click the Actions button.
  5. Select Resume. A pop-up window opens. The reason (device block category) is the same as it was for suspending the device. You cannot change it.
  6. Enter a description.
  7. Click Resume.

Using the API: Suspending and resuming devices

To suspend a device, use the /v3/devices/{id}/suspend POST API.

The API requires you to pass a suspension category.

Use the /v3/device-block-categories/ GET API to list the accepted reasons for suspending a device:

  • maintenance.
  • lost_or_stolen.
  • recalled.
  • security_breach.
  • other.

When you suspend a device, its lifecycle_status changes from enabled to blocked.

To resume a device, use the /v3/devices/{id}/resume POST API.

This API also requires you to pass a suspension category.

Include this reason in the message body of your request, along with a more detailed description. The reasons available for resuming connectivity are the same as those for suspension.

When you resume a device's connection to Device Management, its lifecycle_status changes from blocked to enabled.

Deleting devices

You can only delete devices that register with a development certificate.

We recommend you delete development devices from Device Directory when you reach your 100-device registration limit using your developer certificate.

A device you delete from Device Directory is not accessible through the Device Management APIs and does not appear in Device Management Portal. Delete only developer devices you no longer need.

To reregister a development device you delete from Device Directory, reprogram the device with a new image to generate a new device ID.

Warning: You cannot see deleted devices, and you cannot undo a deletion.

In Portal: Deleting devices

To delete development devices from Device Directory:

  1. Select Device directory > Devices.

  2. From the Execution mode filter dropdown, select Development.

  3. Select the checkbox next to each ID you want to delete, or select the checkbox next to Device ID to delete all devices in the filter.

  4. Click the Actions button, and select Delete devices.

    A confirmation popup window opens.

  5. Click Delete to confirm.

Using the API: Deleting devices

To delete a device, use the /v3/devices/{id}/ DELETE API.