WebSockets

FreeSDN exposes a persistent WebSocket connection at /api/v1/ws that delivers every platform event in real time: device state changes, alert firings, scan progress, agent heartbeats, camera detections, VoIP call events, automation completions, and more. The same transport carries commands to connected agents. This page covers the two WS endpoints, the authentication handshake, the message protocol, subscription filtering, and the security model the server enforces on each connection.

Endpoints

Method	Path	Purpose	Auth
WS	/api/v1/ws	Real-time event stream and agent-command channel	JWT (see below)
GET	/api/v1/ws/stats	Returns the count of currently active connections	authenticated HTTP

The stats endpoint is a plain HTTP GET - use it for dashboards or health checks when you want to know how many clients are connected without opening a socket yourself.

Opening a connection

Use any standards-compliant WebSocket client. The URL scheme is wss:// in production and ws:// in development:

wss://your-domain/api/v1/ws

The server performs two checks during connection setup:

1. Origin validation - for browser connections the Origin header must match CORS_ORIGINS or be same-origin. Connections that fail this check are closed immediately with code 1008 before accept() is called. Agent connections (non-browser) are not subject to the Origin check.
2. Connection caps - the server enforces MAX_WS_PER_USER=25 concurrent connections per user account and MAX_WS_GLOBAL=5000 across all tenants. Exceeding either cap closes the new connection with code 1013 (Try Again Later). When the connection authenticates via cookie or query-string token the cap is enforced before accept(). When the connection authenticates via the auth-message frame, accept() must be called first (so the server can receive the frame); if the cap is exceeded after the auth message arrives the already-upgraded socket is closed with 1013.

Authentication

You must authenticate within 10 seconds of the connection being accepted. Three mechanisms are supported, in order of preference:

1. Auth-message frame (recommended)

Send a JSON frame immediately after the socket opens:

{"type": "auth", "token": "<JWT access token>"}

The server validates the token with the same verify_token logic used by the REST API. On success it sends a connected frame listing all available event types. On failure it closes the connection.

2. Session cookie

If the browser already has the freesdn_access httpOnly cookie set (from a prior /api/v1/auth/login call), the cookie is read during the upgrade handshake automatically. No extra frame is needed.

3. Query-string token (deprecated)

wss://your-domain/api/v1/ws?token=<JWT>

Caution

The ?token= method logs the raw token in access logs and proxy logs. It exists for backward compatibility with older agent builds. Prefer the auth-message frame for any new integration.

What the principal carries

The authenticated principal attached to the connection holds the user’s user_id, org_id, role, permission list, and token_version. The token_version is checked at connection time and re-validated every five minutes (see Session revalidation below).

API keys

Current limitation

WebSocket connections do not currently support API key authentication. The X-API-Key header is not read during the WS upgrade handshake, and passing an API key string as the token field of the auth-message frame will fail - verify_token validates JWTs only and will reject it. The scoped-principal path exists in the REST dependency layer (get_current_user_optional) but is never exercised by the WS endpoint.

If you need a persistent, non-interactive WS client (e.g. an automation script), obtain a short-lived JWT access token via POST /api/v1/auth/login and use the auth-message frame mechanism. WebSocket connections do not support API key authentication in this release.

Message protocol

All messages are JSON objects with a type field that identifies the message kind.

Server → client messages

type	When sent	Key fields
connected	Immediately after successful auth	available_events (array of all EventType values)
event	When a subscribed event fires	event object (see Event shape)
subscribed	After a successful subscribe request	subscriptions (confirmed patterns)
unsubscribed	After an unsubscribe request	subscriptions (removed patterns)
subscription_denied	On a subscribe request for a pattern the caller lacks permission for	patterns (denied list)
filters_set	After a successful set_filters request	site_ids
pong	In response to a ping	timestamp (ISO 8601 server time)
session_revoked	When the server detects the session is no longer valid	-
error	Protocol or validation error	message

Event shape

{
  "type": "event",
  "event": {
    "event_type": "device.state_changed",
    "category": "devices",
    "priority": "normal",
    "organization_id": "<uuid>",
    "payload": {
      "site_id": "<uuid or null>",
      "..."
    }
  }
}

Note

site_id is not a top-level field on the event object. When present, it lives inside payload (e.g. msg.event.payload.site_id). The server reads it from payload internally when enforcing site-scoped delivery (see Site-scoped delivery). Reading msg.event.site_id directly will always return undefined.

Payloads are sanitized before delivery: the server strips any field whose name appears in the _SENSITIVE_PAYLOAD_KEYS set - password, hashed_password, secret, api_key, api_secret, client_secret, token, access_token, refresh_token, private_key, ssh_key, mfa_secret, mfa_backup_codes, credentials, cookie, session_token, and encryption_key - from every outgoing payload, regardless of nesting depth.

Client → server messages

Send these frames after authentication. Frames arrive at a rate limiter capped at five messages per second; exceeding that closes the connection with code 1008.

subscribe

{
  "type": "subscribe",
  "subscriptions": [
    "device.*",
    "alert.fired",
    "discovery.*"
  ]
}

Patterns may use wildcards. Each pattern must be 200 characters or fewer. The server checks every requested pattern against the permission map (see Subscription permissions) and responds with a subscribed frame for allowed patterns and a subscription_denied frame for any that are denied. You can hold up to MAX_SUBSCRIPTIONS_PER_CONN=200 active subscriptions per connection.

unsubscribe

{"type": "unsubscribe", "subscriptions": ["alert.fired"]}

set_filters

Narrow the event stream to one or more sites. The server validates each site_id against your organisation membership and your UserSiteAccess grants - any site you cannot read is rejected silently.

{"type": "set_filters", "site_ids": ["<uuid>", "<uuid>"]}

ping

{"type": "ping"}

The server responds with {"type": "pong", "timestamp": "<ISO 8601 datetime>"}. Use this to keep the connection alive through idle-timeout proxies and to measure round-trip latency.

Subscription permissions

Not every role can subscribe to every event stream. The server maps subscription patterns to permission requirements in app/core/ws_rbac.py. The general principle mirrors the REST permission model:

Event prefix	Required permission	Notes
device.*	device:read	Device state changes, adoption events
alert.*	alert:read	Alert fired/resolved
sla.*	analytics:read	SLA status updates
controller.*	controller:read	Controller sync events
discovery.*	device:read	Scan progress and discovered-device events
vpn.*	vpn:read	VPN tunnel state
pbx.*	device:read	PBX sync progress and call-state events
camera.*	device:read	Camera health and detection events
nvr.*	device:read	NVR-level events (reboot, recording status)
audit.*	audit:read	Audit log entries
security.*	audit:read	Security event stream
settings.*	settings:read	Platform settings changes
user.*	user:read	User account events
admin.*	super_admin only	Administrative events
system.*	super_admin only	Internal system events

The viewer role carries device:read, alert:read, controller:read, vpn:read, analytics:read, and audit:read by default, giving read-only users a broad real-time view that includes device state, alerts, controller sync events, VPN tunnel state, SLA updates, audit log entries, and security events. Only user.* (requires user:read), settings.* (requires settings:read), admin.*, and system.* streams are out of reach for viewers. Unknown prefixes (for example network.*, cameras.*, voip.*, firewall.*, agent.*, automation.*) are denied by default - the server sends a subscription_denied frame and the subscription is silently rejected.

Note

Site-scoped delivery

The server applies site filtering server-side on every broadcast, not just at subscription time:

• If a user has one or more UserSiteAccess grants, the server loads those grants into memory when the connection authenticates and re-loads them every five minutes. Events tagged with a site_id outside those grants are dropped before delivery, even if a matching subscription is active.
• Users with no explicit site grants receive all events for their organisation (backward-compatible behaviour for accounts that pre-date site grants).
• Events with no site_id are delivered only when the event’s payload.user_id matches the connected user (targeted notifications). They are not broadcast to the room.

Session revalidation

Every five minutes the server re-validates the user behind each open connection by querying the database for is_active, deleted_at, and token_version. If any check fails, the server sends a session_revoked frame and closes the connection. Handle this on the client by catching the close event, re-authenticating, and reopening the connection.

ws.addEventListener('message', (ev) => {
  const msg = JSON.parse(ev.data);
  if (msg.type === 'session_revoked') {
    // Re-authenticate and reconnect
  }
});

Site grants are also refreshed on each revalidation cycle, so access additions or removals propagate within five minutes without requiring a reconnect.

Cross-pod fan-out

In a multi-replica deployment (the Max tier HA configuration), targeted send_to_user calls first fan out to all connections on the local pod, then publish a message to a Valkey (Redis-compatible) pubsub channel so other pods can deliver to their local connections. Each pod has exactly one subscriber on that channel; the delivery is best-effort - double-delivery to the originating pod is prevented via a pod_id (source_pod_id) field in the envelope, and receiving pods deliver only to their own local connections for the target user.

When REDIS_URL is unset (single-pod development), the pubsub step is skipped automatically and all connections are served locally.

Agent-control messages

The FreeSDN agent (freesdn-agent, MIT, alpha) connects to a separate WebSocket endpoint at /api/v1/agents/ws/{agent_id}. Agents authenticate by sending {"agent_key": "...", "site_id": "..."} as the first frame after the connection is accepted - not a JWT. If an Origin header is present (browser-based CSWSH probe), the server validates it against CORS_ORIGINS via _validate_ws_origin_optional; non-browser agents that omit Origin are allowed through. The /api/v1/ws endpoint described on this page is for browser and API clients only.

Once an agent connection is established, the server can push task commands to it. The WS channel is bidirectional: the server pushes task commands to the agent, and the agent sends back heartbeats, scan progress, scan results, and fingerprint reports over the same connection. The agent also acknowledges task completion via REST (PATCH /api/v1/agents/tasks/{task_id}).

Key agent REST endpoints that work alongside the WS channel:

Method	Path	Purpose
POST	/api/v1/agents/register	Register agent, receive agent ID
POST	/api/v1/agents/{agent_id}/heartbeat	Push heartbeat (triggers WS agent.heartbeat event)
GET	/api/v1/agents/{agent_id}/tasks/pending	Poll pending tasks (agents may poll rather than use WS)
PATCH	/api/v1/agents/tasks/{task_id}	Acknowledge or update task status
POST	/api/v1/agents/{agent_id}/scan	Dispatch an interactive scan via live WS
GET	/api/v1/agents/{agent_id}/scan/{task_id}	Poll scan progress

Complete connection example

The following is a minimal browser-side client that authenticates with an auth-message frame, subscribes to device and alert events, and handles pong and session revocation.

async function openEventStream(accessToken) {
  const ws = new WebSocket('wss://your-domain/api/v1/ws');

  ws.addEventListener('open', () => {
    // Step 1: authenticate
    ws.send(JSON.stringify({ type: 'auth', token: accessToken }));
  });

  ws.addEventListener('message', (ev) => {
    const msg = JSON.parse(ev.data);

    switch (msg.type) {
      case 'connected':
        // Step 2: subscribe after successful auth
        ws.send(JSON.stringify({
          type: 'subscribe',
          subscriptions: ['device.*', 'alert.*'],
        }));
        break;

      case 'event':
        console.log('event received', msg.event.event_type, msg.event.payload);
        break;

      case 'session_revoked':
        ws.close();
        // Re-obtain a fresh token and reconnect
        break;

      case 'error':
        console.error('WS error', msg.message);
        break;
    }
  });

  // Keep-alive ping every 30 s
  const ping = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ type: 'ping' }));
    }
  }, 30_000);

  ws.addEventListener('close', () => clearInterval(ping));

  return ws;
}

Security model summary

Concern	Mechanism
Cross-site WebSocket hijacking	Origin header validated against CORS_ORIGINS before accept
Token leakage	Auth-message frame is the recommended path; ?token= deprecated
Cross-tenant event leakage	Org-ID compared on every broadcast; mismatch drops the event fail-closed
Privilege escalation via subscription	Subscription patterns checked against RBAC permission map per-pattern
Stale session	Token version and user active status re-checked every 5 minutes
Site-scope leakage	UserSiteAccess grants loaded at connect and refreshed every 5 minutes
Payload secret leakage	Password/token/secret fields stripped from every outgoing payload
Connection flooding	Global cap 5000, per-user cap 25, inbound rate limit 5 msg/s

Caution

Multi-tenancy is enforced at the application layer. There is no PostgreSQL row-level security on the event tables - the org-ID broadcast filter in the WebSocket server is the isolation boundary. Do not assume database-level isolation.

Note

The FreeSDN React frontend uses the same WebSocket endpoint. It reads the freesdn_access httpOnly cookie automatically and does not require an auth-message frame because the cookie is sent with the upgrade request.

Next steps

• Authentication - obtain a JWT access token to use in the auth-message frame
• Authentication - obtain a short-lived JWT access token via POST /api/v1/auth/login for use in non-interactive WS clients (API key WS support is not yet available)
• Using the API - CSRF, rate limits, and error shapes that also apply to WebSocket clients
• Agents - agent registration, task dispatch, and the REST endpoints that complement the WS channel