Download OpenAPI specification:
Configure and monitor the SmartTouch Remote Access Service.
This API covers the operational surface of the Remote Access Service itself: broker health, protocol configuration, and agent registration policy. For session lifecycle operations, see the Session API. For device agent status, see the Device API.
| Resource | Description |
|---|---|
/remote-access/health |
Broker health and active connection count |
/remote-access/config |
Service-level protocol and TTL configuration |
/remote-access/protocols |
Enabled session protocols and their role requirements |
/remote-access/broker |
Broker connection metrics and node status |
/remote-access/agents |
All connected agent instances across devices |
| Operation | Minimum role |
|---|---|
| Read health and metrics | developer |
| Read configuration | developer |
| Update configuration | platform-engineer |
| View all agents | platform-engineer |
| Disconnect an agent | administrator |
Returns the health status of the Remote Access Service and its session broker. Use this endpoint to confirm the service is operational before opening sessions.
{- "status": 200,
- "data": {
- "service": "remote-access-service",
- "health": "healthy",
- "broker": {
- "status": "online",
- "nodes": 3,
- "active_connections": 142
}, - "checked_at": "2026-06-08T09:00:00Z"
}
}Returns the active service-level configuration for the Remote Access Service.
{- "status": 200,
- "data": {
- "broker_url": "wss://broker.smarttouch.local:8443",
- "default_ttl_seconds": 3600,
- "max_ttl_seconds": 28800,
- "max_sessions_per_device": 3,
- "allowed_protocols": [
- "diagnostics",
- "shell",
- "file-transfer"
], - "agent_heartbeat_interval_seconds": 30,
- "agent_reconnect_backoff_seconds": 10,
- "last_updated_at": "2026-06-07T12:00:00Z",
- "last_updated_by": "platform-engineer@example.com"
}
}Update one or more service-level configuration values. Only the fields included in the request body are changed.
Changes take effect within 30 seconds. Active sessions are not interrupted.
Requires the platform-engineer role.
| default_ttl_seconds | integer [ 60 .. 28800 ] |
| max_ttl_seconds | integer [ 60 .. 28800 ] |
| max_sessions_per_device | integer [ 1 .. 10 ] |
| allowed_protocols | Array of strings non-empty Items Enum: "diagnostics" "shell" "file-transfer" |
| agent_heartbeat_interval_seconds | integer [ 10 .. 300 ] |
| agent_reconnect_backoff_seconds | integer [ 1 .. 60 ] |
{- "default_ttl_seconds": 1800
}{- "status": 200,
- "data": {
- "broker_url": "wss://broker.smarttouch.local:8443",
- "default_ttl_seconds": 3600,
- "max_ttl_seconds": 28800,
- "max_sessions_per_device": 3,
- "allowed_protocols": [
- "diagnostics"
], - "agent_heartbeat_interval_seconds": 30,
- "agent_reconnect_backoff_seconds": 10,
- "last_updated_at": "2019-08-24T14:15:22Z",
- "last_updated_by": "platform-engineer@example.com"
}
}Returns the full list of session protocols supported by the platform, including each protocol's description, required role, and enabled state.
{- "status": 200,
- "data": [
- {
- "name": "diagnostics",
- "description": "Read-only diagnostic commands on the device",
- "required_role": "developer",
- "enabled": true,
- "max_concurrent_per_device": 1
}, - {
- "name": "shell",
- "description": "Full interactive shell on the device",
- "required_role": "platform-engineer",
- "enabled": true,
- "max_concurrent_per_device": 1
}, - {
- "name": "file-transfer",
- "description": "Upload and download files to and from the device",
- "required_role": "administrator",
- "enabled": true,
- "max_concurrent_per_device": 1
}
]
}Returns connection metrics and node-level status for the session broker.
Use this endpoint to diagnose broker capacity or connectivity issues.
Requires the platform-engineer role.
{- "status": 200,
- "data": {
- "status": "online",
- "nodes": [
- {
- "id": "broker-node-01",
- "status": "online",
- "active_connections": 52,
- "address": "wss://broker-01.smarttouch.local:8443"
}, - {
- "id": "broker-node-02",
- "status": "online",
- "active_connections": 47,
- "address": "wss://broker-02.smarttouch.local:8443"
}, - {
- "id": "broker-node-03",
- "status": "online",
- "active_connections": 43,
- "address": "wss://broker-03.smarttouch.local:8443"
}
], - "total_active_connections": 142,
- "total_sessions_opened_today": 1024,
- "checked_at": "2026-06-08T09:00:00Z"
}
}Returns all Remote Access Agent instances currently connected to the broker.
Each entry maps to a device. Use this endpoint to audit which devices are online.
Requires the platform-engineer role.
| broker_node | string Example: broker_node=broker-node-01 Filter agents connected to a specific broker node |
| page | integer Default: 1 |
| per_page | integer <= 500 Default: 100 |
{- "status": 200,
- "data": [
- {
- "device_id": "sensor-001",
- "agent_version": "1.4.2",
- "connected_at": "2026-06-08T08:55:32Z",
- "broker_node": "broker-node-01",
- "latency_ms": 12
}, - {
- "device_id": "sensor-002",
- "agent_version": "1.4.1",
- "connected_at": "2026-06-08T07:30:00Z",
- "broker_node": "broker-node-02",
- "latency_ms": 18
}
], - "meta": {
- "page": 1,
- "per_page": 100,
- "total": 2
}
}Forcibly disconnects the Remote Access Agent for a device from the broker. All open sessions to this device are closed immediately.
The agent will attempt to reconnect according to its backoff policy. Use this endpoint to force a reconnect cycle when an agent appears stuck.
Requires the administrator role.
| deviceId required | string Example: sensor-001 Device ID of the connected agent |
{- "status": 200,
- "data": {
- "device_id": "sensor-001",
- "disconnected_at": "2026-06-08T09:30:00Z",
- "sessions_closed": 1
}
}