---
title: "Create TCP Proxy Session"
method: POST
path: "/v1/tcp-proxy"
tags: ["TCP Proxy"]
---

# Create TCP Proxy Session

`POST /v1/tcp-proxy`

Create a TCP proxy session and return a short-lived token for WebSocket connection.
This is the first step in establishing a TCP proxy connection. 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 to create a TCP tunnel
2. Server establishes connection to target via agent and returns a session token
3. Connect to `/v1/tcp-proxy/{token}` WebSocket endpoint (no auth header needed)

This flow is designed to work with browser WebSocket API which cannot send
custom Authorization headers.

**Required Permissions:**
- System access right: SYSTEM_ACCESS_SETUP_TCP_PROXY
- Object access right: OBJECT_ACCESS_CONTROL on the target or proxy object

## Request body

- object
  - `allowControlMessages` boolean — If true, server will send JSON control messages in text frames (default is false)
  - `proxyId` integer — Proxy node ID or zone object ID. If specified, the connection will be established through this proxy node. Either proxyId or nodeId must be specified.
  - `nodeId` integer — Target node ID. If proxyId is not specified, the server will automatically select the appropriate proxy for this node. Either proxyId or nodeId must be specified.
  - `address` string, ip-address — Target IP address. Required when proxyId is specified. When using nodeId, the node's primary IP address is used automatically.
  - `port` integer, required — Target TCP port number (required).

## Response `201`

TCP proxy 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 - Invalid parameters. Possible reasons: - Port parameter missing - Invalid IP address format - Invalid proxy object type
- `401` — Unauthorized - Authentication token missing or invalid
- `403` — Forbidden - User does not have required permissions. Either SYSTEM_ACCESS_SETUP_TCP_PROXY or OBJECT_ACCESS_CONTROL is missing.
- `404` — Object not found - Invalid nodeId or proxyId
- `502` — Bad Gateway - Cannot establish connection to agent. Agent may be unreachable or TCP proxy setup failed.
- `503` — Service Unavailable - No proxy node available in zone

---

[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/14d93e5115dd/schema)