WebSocket Gateway

WebSockets keep a connection open. The client and provider can each send and receive messages through this connection. Verdictan verifies the credential when the connection opens and applies policy to complete text messages.

Use this only with a provider that supports WebSocket connections at the upstream route below. HTTP support does not show WebSocket support. For ordinary streamed text answers, start with SSE.

Content rewriting is not supported on this path. A redact or escalate verdict records the decision but forwards the initial text. Use HTTP or SSE when policy must change content before delivery.

Routes

Client route	Upstream 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 adds the /ws suffix only when it connects to Verdictan. The gateway removes the suffix when it connects to the selected upstream. The HTTP request families do not accept the /ws paths.

Connect

Install the websocat client before you use this example. Keep your gateway open.

Send a client API token, Access Key, or Gateway Key in the Authorization header of the upgrade request. Do not use the gateway runtime token as the client credential.

export VERDICTAN_CLIENT_TOKEN="replace-with-client-token"

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

For a published TLS endpoint, use wss://<published-hostname>/v1/responses/ws. The gateway validates publication and token policy during the handshake. After the handshake, it replaces the client Authorization header with the resolved upstream provider credential.

After connection, send a message in the upstream provider's supported protocol. A completed handshake shows connectivity, not a model response without an error. Examine the provider response and the recorded frame decision.

Provider routing

The gateway selects an HTTP-capable provider target and resolves its provider credential before it upgrades the connection. To pin one configured target, send its ID in the X-Verdictan-Provider header of the upgrade request.

An unknown pin fails the handshake with a structured 400 response. A target that is configured only as an execution target does not support WebSocket traffic.

Frame governance

The gateway governs each complete text frame:

Frame	Policy input	Result
Client text	Parsed JSON, or the raw text when the frame is not JSON, at the pre-request stage	Forwarded on allow, redact, or escalate, session closed with code 1008 on block
Upstream text	Parsed JSON, or the raw text when the frame is not JSON, at the pre-response stage	Forwarded on allow, redact, or escalate, session closed with code 1008 on block
Text that starts with { or [ but has incorrect JSON syntax	None	Session closed with code 1008 and reason code request.validation_failed
Binary	None	Session closed with code 1003 and reason code policy.unsupported_transport
Ping, pong, close	None	Passed through as part of the connection lifecycle

Each governed data frame emits one websocket_frame_decision event with the frame sequence, direction, type, decision, and reason code.

Limits

• The proxy has no public declarative config keys. transport: websocket, ping_interval_secs, and idle_timeout_secs are not fields in the policy config.
• The gateway does not buffer a session. A block verdict closes the session at the frame that caused it, and frames that the client received stay delivered.
• The policy receives non-JSON text without a data structure. A control that uses a parsed request or response cannot evaluate this text.

Next steps

• Runtime Request Families: compare the WebSocket family with the HTTP and SSE families.
• Streaming and SSE: use SSE when the gateway must buffer or rewrite output.
• Provider Configuration: configure the provider targets that the WebSocket routes select.