---
title: "Create Remote Control Session"
method: POST
path: "/v1/objects/{object-id}/remote-control"
tags: ["Objects", "TCP Proxy"]
---

# Create Remote Control Session

`POST /v1/objects/{object-id}/remote-control`

Create a remote control (VNC) session for a node and return a short-lived token
for WebSocket connection. This is a convenience endpoint that automatically
determines VNC connection parameters based on the node's configuration.

The endpoint uses the node's configured VNC port and proxy settings to establish
a TCP tunnel. The returned token should be used to connect to the WebSocket
endpoint `/v1/tcp-proxy/{token}`.

**Two-Phase Authorization Flow:**
1. Call this endpoint with Bearer token authentication
2. Server establishes VNC tunnel via agent and returns a session token
3. Connect to `/v1/tcp-proxy/{token}` WebSocket endpoint (no auth header needed)

**Required Permissions:**
- System access right: SYSTEM_ACCESS_SETUP_TCP_PROXY
- Object access rights: OBJECT_ACCESS_READ and OBJECT_ACCESS_CONTROL on the node

## Path parameters

- `object-id` integer, required

## Request body

- object
  - `allowControlMessages` boolean — If true, server will send JSON control messages in text frames (default is false)

## Response `201`

Remote control session created successfully.

- object
  - `token` string, uuid — Session token for WebSocket connection
  - `expiresIn` integer — Token validity period in seconds
  - `wsUrl` string — WebSocket URL path to connect to

## Other responses

- `400` — Bad Request - Object is not a node or VNC port not configured.
- `401` — Unauthorized - Authentication token missing or invalid
- `403` — Forbidden - User does not have required permissions. Either SYSTEM_ACCESS_SETUP_TCP_PROXY, OBJECT_ACCESS_READ, or OBJECT_ACCESS_CONTROL is missing.
- `404` — Object not found - Invalid object ID
- `502` — Bad Gateway - Cannot establish connection to agent. Agent may be unreachable or TCP proxy setup failed.
- `503` — Service Unavailable - No proxy node available

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/versions/ee1f54ee3abd/schema)