IoT Remote Command Execution using REST API.

Today, 3 factors affect the work dynamics of companies of all sizes — small, medium and large — around the world today:

  • The pandemic situation,
  • Geographically distributed workforce
  • The trend towards automation (reduce human involvement/errors)

These 3 factors drive the need for secure remote access to resources such as servers, IoT devices and cloud resources. These resources are not centralized in a single location such as a corporate Datacenter, but they are distributed across different geographical regions.

Commonly, remote command or remote script execution on servers and IoT devices is performed using SSH. This is OK for one-off accesses. But not suited well for repeated tasks/jobs. Moreover, it is not easy and straightforward to automate remote command execution via SSH.

In this article, I’ll discuss an elegant, easy and secure way of executing remote commands or jobs using REST APIs.

No. You don’t have to run an SSH server to use this feature. You could request remote jobs to run on your private devices or servers via REST APIs.

Overall Strategy:

We’ll install a simple, secure and lightweight SocketXP agent to run in your server or IoT device. The agent would connect your server privately and securely using an SSL/TLS tunnel to our SocketXP Cloud API Gateway. You could then access the Cloud API Gateway using a secure authentication token assigned exclusively for you. You could then simply submit jobs to execute in your remote servers via our REST APIs.

Let’s get started.

Install and Setup SocketXP Agent

Follow the instructions here to download, install and setup SocketXP agent on your server or IoT device.

Note: You don’t have to run an SSH server (port 22) to run this agent. You could even point the agent to connect to some local unused port such as 52233.

Submit a Remote Command

Here is our complete list of APIs to execute remote jobs on your servers.

First, let’s submit a remote job to run using the following curl command. You could use the Postman tool to perform the same request.

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '{“JobName”: “test-job-123”, “DeviceId”: "device-12345”, “Command”: “ls -l /home/test-user | grep script” }'

The response to this POST API call, on success (200 OK), would look something like this.

{“JobId”: ”9b4461f7–5c0a-419c-8157-e57c879f4ade”}

Now you could retrieve the status or the result of the job using the above JobId, as shown below.

curl–5c0a-419c-8157-e57c879f4ade \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-auth-token-goes-here>"

And the response to the curl request would look like this:

”Command”:”ls -l /home/test-user | grep script”,
”StartTime”:”Feb 22 2021 07:48”,
”EndTime”:”Feb 22 2021 07:49”,
”Result”:”-rwxrwxrwx 1 test-user test-user 0 Feb 20 05:47 script”

The result field will have the execution result (output/errors) of the remote command executed.

Here are the additional sample remote commands you could execute on a remote server or IoT device using SocketXP API Gateway infrastructure.

“sh /home/john/”
“python /home/john/”
"service sshd restart"
"echo 'This is the content of the file.' > /home/test-user/config"


The following are the advantages of using SocketXP REST APIs to execute remote commands or jobs:

  • secure access via JWT token and TLS connection to the API Gateway
  • ability to automate the API’s using a python or shell script.
  • execute remote commands without having to manually login to the SSH server.
  • Ability to schedule a job to be run on a cluster of servers or nodes or devices.
  • Ability to label a subgroup of servers and submit a job for the label or the subgroup only.
  • Ability to execute a job at a particular time in the future.
  • Ability to invoke a registered webhook API to notify the admin when the job completes. (pull vs push advantage).
  • And many more…

Please give a try and let us know feedback.

If you have a need to customize or add a new functionality to our APIs, feel free to write to us at:

Ganesh Velrajan is the founder of SocketXP. Learn more about SocketXP Remote Access Solutions at

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store