Skip to main content

WebSocket Gateway

The gateway exposes two WebSocket upgrade routes:

Client routeUpstream route
GET /v1/chat/completions/ws/v1/chat/completions through ws:// or wss://
GET /v1/responses/ws/v1/responses through ws:// or wss://

The client uses the /ws suffix only when it connects to Verdictan. The gateway removes that suffix when it connects to the selected upstream.

Connect​

Send an application API token, Access Key, or Gateway Key in the WebSocket upgrade request. Do not use the connected gateway's runtime service token as the client credential.

For example, with a WebSocket client that supports custom headers:

export VERDICTAN_REQUEST_TOKEN="vdt_..."

websocat \
  -H="Authorization: Bearer ${VERDICTAN_REQUEST_TOKEN}" \
  ws://127.0.0.1:41002/v1/responses/ws

Use wss://<published-hostname>/v1/responses/ws for a published TLS endpoint. The gateway checks publication and token policy during the handshake.

Provider routing​

The gateway selects an HTTP-capable provider target. It resolves that provider's upstream authentication before it upgrades the connection. If a target pin is necessary, pin a configured target:

X-Verdictan-Provider: provider-target-id

An unknown pin fails the handshake with a structured 400 response. A target implemented only as an execution target cannot support WebSocket traffic.

Frame behavior and policy boundary​

The gateway authenticates the client one time during the handshake. It replaces the client authorization header with the resolved upstream credential.

The gateway then governs each complete text frame in each direction:

  • Client text uses the pre-request policy stage.
  • Upstream text uses the pre-response policy stage.
  • JSON text uses its parsed request or response content.
  • Non-JSON text uses its text content as policy input.
  • Malformed JSON-like text closes the session with code 1008.
  • A blocking policy verdict closes the session with code 1008.
  • Binary frames are not supported. The gateway records policy.unsupported_transport and closes the session with code 1003.

Ping, pong, and close frames continue through the connection lifecycle. Each governed data-frame result emits websocket_frame_decision evidence.

warning

WebSocket frame governance does not rewrite text. If a policy returns a redact or escalate verdict, the gateway records the verdict and forwards the original text. Use the HTTP or SSE routes when the gateway must rewrite content before delivery.

There are no public transport: websocket, ping_interval_secs, or idle_timeout_secs declarative config keys for this proxy.

Next steps​