API docs by Redocly

SmartTouch Session API (1.0.0)

Download OpenAPI specification:

URL: https://docs.smarttouch.io License: Proprietary

Manage remote access sessions to IoT devices on the SmartTouch Cloud Platform.

A session is an authenticated tunnel opened through the Remote Access Service between a client (developer, platform engineer, administrator, or automation) and a device's Remote Access Agent.

Session lifecycle

POST /remote-access/sessions  →  session.opened  (audit event)
     ↓ (session active)
DELETE /remote-access/sessions/{id}  →  session.closed  (audit event)

Sessions also close automatically when their TTL expires, producing a session.expired audit event.

Protocol permissions

Protocol Minimum role Description
diagnostics developer Read-only diagnostic commands
shell platform-engineer Full interactive shell on the device
file-transfer administrator Upload and download files

Authentication

All endpoints require a bearer token obtained via stctl auth token.

Base URL

https://api.<your-platform-domain>/v1

Related APIs

Sessions

Remote access session lifecycle — open, inspect, list, and close sessions

List sessions

Returns remote access sessions. Developers see only their own sessions. Administrators see sessions for all users.

Authorizations:
bearerAuth
query Parameters
device_id
string
Example: device_id=sensor-001

Filter sessions by device ID

protocol
string
Enum: "shell" "diagnostics" "file-transfer"

Filter sessions by protocol

status
string
Enum: "open" "closed"

Filter sessions by status

since
string <date-time>
Example: since=2026-06-08T00:00:00Z

Return sessions opened after this ISO 8601 timestamp

page
integer >= 1
Default: 1
per_page
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": [
    ],
  • "meta": {
    }
}

Open a session

Opens a new remote access session to a device.

The device's Remote Access Agent must be online. Verify agent status with GET /devices/{deviceId}/agent-status before calling this endpoint.

Only one session per protocol per device can be open at a time. If a session of the requested protocol is already open, the endpoint returns 409 Conflict.

On success, the response includes a websocket_url. Use this URL to connect a WebSocket client for interactive sessions. stctl remote-access open handles this automatically.

Authorizations:
bearerAuth
Request Body schema: application/json
required
device_id
required
string

Target device ID

protocol
required
string
Enum: "shell" "diagnostics" "file-transfer"

Session protocol. Determines the level of access granted.

  • diagnostics — read-only inspection (developer+)
  • shell — full interactive shell (platform-engineer+)
  • file-transfer — upload/download files (administrator only)
ttl_seconds
integer [ 60 .. 28800 ]
Default: 3600

Session time-to-live in seconds. The session closes automatically when the TTL elapses.

Responses

Request samples

Content type
application/json
Example
{
  • "device_id": "sensor-001",
  • "protocol": "diagnostics",
  • "ttl_seconds": 1800
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "data": {
    }
}

Get a session

Returns details for a single session, including its current status, byte counters, and the trace ID for log correlation.

Authorizations:
bearerAuth
path Parameters
sessionId
required
string
Example: sess-9c4d2e

Unique session identifier (e.g., sess-9c4d2e)

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Close a session

Closes an open session immediately. The device agent terminates the tunnel within 5 seconds. A session.closed event is written to the audit log.

Closing an already-closed session returns 404 Not Found.

Authorizations:
bearerAuth
path Parameters
sessionId
required
string
Example: sess-9c4d2e

Unique session identifier (e.g., sess-9c4d2e)

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}