Device suspension

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.

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

Suspension is useful in situations where a device is:

• Lost.
• Stolen.
• Resold.
• Malfunctioning.
• Otherwise compromised.

There are two ways to suspend devices:

• Using Device Management Portal.
• Directly through the APIs.

Suspending and resuming connection to devices in Portal

To suspend a device:

1. Log in to Device Management Portal.
2. Select Device directory > Devices from the menu on the left side of the page.
3. To select devices to suspend, either:
   • Tick the checkbox next to each ID to suspend them one at a time.
   • 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.
4. Click the Actions button and select Suspend or Resume. A pop-up appears.
5. Click the drop-down menu to select a reason for suspension. This is a required field. Valid reasons are:
   • Lost or stolen.
   • Recalled.
   • Maintenance.
   • Security breach.
   • Other. This reason will show in device attributes as last_system_suspended_category or last_operator_suspended_category.
6. Enter a description.
7. Click Suspend.

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

To resume a device's connection to Device Management:

1. Log in to Device Management Portal.
2. Select Device directory > Devices from the menu on the left side of the page.
3. To select devices to suspend, either:
   • Tick the checkbox next to each ID to resume connection one device at a time.
   • 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.
4. Click the Actions button and select Resume. A pop-up appears. The suspension category is the same as when you suspended the device, and you cannot change it.
5. Enter a description.
6. Click Resume.

The device can now reconnect to Device Management. The time between reconnection attempts increases exponentially, up to one week, so the device might not reconnect immediately.

Suspending and resuming connection to devices with the APIs

There are two important operations related to device suspension: suspend and resume. See the Device Directory API documentation for a full list of resourced.

Stop connection to Device Management

To suspend a device, you must also give a reason by choosing a suspension category. Include this reason in the message body of your POST request, along with a more detailed description.

Use POST /v3/devices/{id}/suspend.

Note: Include the API key as a header in all requests.

Example:

curl -X POST 'https://api.us-east-1.mbedcloud.com/v3/devices/{id}/suspend' \
  -H 'Authorization: Bearer <api_key>' \
  -d '{
    "category" : "maintenance",
    "description" : "Suspended for maintenance."
  }'

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

Retrieve valid suspension categories

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

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

Restoring connection to Device Management

Returning a device to service allows it to reconnect to Device Management, and restores all API functionality. The time between reconnection attempts increases exponentially, up to one week, so the device might not reconnect immediately. You must also give a reason for reconnection by choosing a suspension category. Include this reason in the message body of your POST request, along with a more detailed description. The categories to resume connectivity are the same as those to suspend it.

Use command POST /v3/devices/{id}/resume.

Note: Include the API key as a header in all requests.

Example:

curl -X POST 'https://api.us-east-1.mbedcloud.com/v3/devices/<id>/resume' \
  -H 'Authorization: Bearer <api_key>' \
  -d '{
    "category" : "lost_or_stolen",
    "description" : "Device found."
  }'

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