Skip to main content

Channel API (Secure Remote Access)

Manage gateways, devices, sessions, access policies, and audit logs.

Dashboard​

GET /api/v1/channel/dashboard

Returns gateway counts, device totals, active sessions, recent activity, and pending access requests.

Gateways​

List Gateways​

GET /api/v1/channel/gateways

Provision Gateway​

POST /api/v1/channel/gateways/provision
{
  "site_id": "uuid",
  "name": "Plant Alpha Gateway",
  "hardware_model": "ctrlx-core"
}

Response includes tunnel configuration, install script, and gateway credentials.

Get Gateway Detail​

GET /api/v1/channel/gateways/:id

Gateway Heartbeat​

PUT /api/v1/channel/gateways/:id/heartbeat

Called by the gateway agent to report status, firmware version, and health metrics.

Decommission Gateway​

DELETE /api/v1/channel/gateways/:id

Removes tunnel peer, terminates active sessions, and deletes the gateway record.

Channel Devices​

List Devices​

GET /api/v1/channel/devices?gateway_id=YOUR_uuid

Register Device​

POST /api/v1/channel/devices
{
  "gateway_id": "uuid",
  "name": "PLC-Line4-Main",
  "ip_address": "192.168.10.50",
  "allowed_protocols": ["ssh", "http", "modbus"],
  "recording_policy": "mandatory"
}

Update Device​

PUT /api/v1/channel/devices/:id

Remove Device​

DELETE /api/v1/channel/devices/:id

Sessions​

List Sessions​

GET /api/v1/channel/sessions?status=active&gateway_id=YOUR_uuid&limit=50

Connect (Start Session)​

POST /api/v1/channel/sessions/connect
{
  "device_id": "uuid",
  "protocol": "ssh",
  "user_id": "clerk-user-id"
}

The broker validates:

  • Device exists and gateway is connected
  • Protocol is allowed for the device
  • User has permission (access policy check)
  • Time window is active
  • Concurrent session limit not exceeded
  • Approval exists (if required)

Response includes session ID and connection parameters (proxy URL for HTTP, Guacamole endpoint for RDP/VNC/SSH).

Disconnect (End Session)​

PUT /api/v1/channel/sessions/:id/disconnect
{
  "reason": "user"
}

Access Policies​

List Policies​

GET /api/v1/channel/policies?device_id=YOUR_uuid

Create Policy​

POST /api/v1/channel/policies
{
  "device_id": "uuid",
  "role": "engineer",
  "allowed_protocols": ["ssh", "http"],
  "access_windows": [
    { "days": ["mon","tue","wed","thu","fri"], "start": "06:00", "end": "22:00", "tz": "America/New_York" }
  ],
  "require_approval": false,
  "require_mfa": true,
  "max_session_minutes": 480,
  "max_concurrent": 2,
  "read_only": false
}

Delete Policy​

DELETE /api/v1/channel/policies/:id

Access Requests​

List Requests​

GET /api/v1/channel/requests?status=pending

Submit Request​

POST /api/v1/channel/requests
{
  "requester_id": "clerk-user-id",
  "device_id": "uuid",
  "protocol": "rdp",
  "requested_start": "2026-03-10T09:00:00Z",
  "requested_end": "2026-03-10T17:00:00Z",
  "justification": "Firmware update for PLC-Line4"
}

Review Request​

PUT /api/v1/channel/requests/:id/review
{
  "status": "approved",
  "reviewer_id": "clerk-admin-id",
  "review_notes": "Approved for maintenance window"
}

Audit Log​

GET /api/v1/channel/audit?user_id=YOUR_id&action=YOUR_action&resource_type=YOUR_type&limit=100

Returns chronological audit entries with action, resource, user, timestamp, and details.