Skip to main content
The WebSocket endpoint is the core of WireSocket. All Yjs document updates, awareness state (presence, cursors), and heartbeats flow through this high-performance connection.

​
Endpoint

wss://{region}.wiresocket.net/{documentName}
Example: wss://eu-central-1.wiresocket.net/my-document-id

​
Authentication

The Data Plane supports three ways to authenticate the WebSocket handshake. Method 1 is recommended as it keeps the token out of browser history and server logs.
MethodImplementation
1. WebSocket Sub-protocolprotocols: ['access_token', 'YOUR_JWT']
2. Query Parameterwss://{region}.wiresocket.net?token=YOUR_JWT
3. Authorization HeaderHeaders: { 'Authorization': 'Bearer YOUR_JWT' }

​
Connection Example

Using the standard y-websocket provider: 
import * as Y from "yjs";
import { WebsocketProvider } from "y-websocket";

const ydoc = new Y.Doc();

// 1. Resolve URL via Discovery API first
// 2. Initialize provider
const provider = new WebsocketProvider(
  "wss://eu-central-1.wiresocket.net", // Resolved URL
  "my-document-id",
  ydoc,
  {
    // Pass JWT via sub-protocol
    protocols: ["access_token", "YOUR_JWT"],
  },
);

​
Close Codes (Error Reference)

If a connection is rejected or closed, the Data Plane returns one of the following codes:
CodeNameDescription
4001Missing TokenNo JWT was provided in the handshake.
4002Invalid TokenToken is expired, malformed, or has an invalid signature.
4003ForbiddenThe token is valid but the tenantId or appId claims are rejected.
4004Connection LimitYour application has reached its concurrent connection cap.
4005Document LimitYour application has reached its concurrent document cap.
4006Rate LimitRequest frequency from this IP is too high.
4007Invalid NameThe document name violates internal naming rules.
4008User LimitThe max number of users per document (maxUsersPerDoc) is reached.
4009Wrong RegionThe document is active in another region. The reason field will contain REDIRECT:wss://....

​
Handling Redirection (4009)

If you receive a 4009 close code, your client should parse the reason string to find the correct regional URL and reconnect immediately: 
provider.ws.onclose = (event) => {
  if (event.code === 4009 && event.reason.startsWith("REDIRECT:")) {
    const newUrl = event.reason.replace("REDIRECT:", "");
    console.log("Redirecting to:", newUrl);
    // Trigger reconnection logic with newUrl
  }
};
Last modified on March 3, 2026