Copy page

Documentation

Automating Device Remediation

The API executes remediation tasks across one or more devices and reports the outcome of each, so remediation can be driven from the systems and workflows your teams already operate, or built into new workflows and automations of your own.

Scenarios

• Scheduled credential rotation. Rotate device passwords across the fleet on a defined schedule from your orchestration system.
• Ticket-driven remediation. Execute a task from your ITSM or ticketing tool and post the result back to the ticket.
• Certificate lifecycle automation. Rotate SSL certificates ahead of expiry as part of your certificate management process.
• Response to monitoring. Execute remediation automatically from a condition detected through Monitoring.

Check task availability

Not every device supports every task. The availableTask object on a device reports which tasks can be executed on it, so filter the target devices before executing:

Code
"availableTask": {
  "hardenDevice": false,
  "restartDevice": true,
  "rotate8021xCertificate": false,
  "rotatePassword": true,
  "rotateSslCertificate": true,
  "upgradeFirmware": true
}

Execute a task

A single request executes a task across any number of devices, and returns the taskId used to track it:

Code
curl -X POST "https://api.securithings.com/v1/tasks" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d '{
       "taskType": "restartDevice",
       "devices": [
         { "deviceId": "9ff559ee-38b6-11f1-81cb-465864a35d0a" },
         { "deviceId": "dc7d4ef1-6bf9-11f1-b083-d27bafcacdf8" }
       ]
     }'

Code
{ "taskId": "23bpozz1mpjjedtr" }

Tasks run asynchronously. The execution and polling pattern, the available task types, and the per-task-type payloads are described in Asynchronous Tasks.

Verify the outcome

Poll GET /v1/tasks/{id} until every device task has a status of completed, then read the result of each device task. Device tasks that did not succeed can be retried independently of the rest.

Code
curl "https://api.securithings.com/v1/tasks/23bpozz1mpjjedtr" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <token>"