Connections

Active connections, user management, and room broadcasting API

Connections API

Manage active WebSocket connections, users, and room operations.

Admin session required: All connection management endpoints require an authenticated admin session, the session_token cookie of a user with the admin role. A valid non-admin session receives 403. These are operator-only administrative operations.

Get Active Connections

Authentication Required

List all active WebSocket connections in the system. Rate-limited to 30 requests per minute.

Endpoint: GET /api/connections/active

curl -X GET "$BASE_URL/api/connections/active" \
  -b cookies.txt

interface Connection {
  id: string
  clientId: string
  userId: string
  roomId: string
  presenterName: string
  isHost: boolean
  joinedAt: string
  connectionStatus: 'connected' | 'disconnected'
}

const connections: Connection[] = await $fetch('/api/connections/active', {
  // session cookie (session_token) sent automatically same-origin
})

import requests

response = requests.get(
    "$BASE_URL/api/connections/active",
    headers={"Cookie": f"session_token={token}"}
)
connections = response.json()

req, _ := http.NewRequest("GET",
    "$BASE_URL/api/connections/active", nil)
req.Header.Set("Cookie", "session_token="+token)
resp, _ := http.DefaultClient.Do(req)

<?php
$response = file_get_contents(
    '$BASE_URL/api/connections/active',
    false,
    stream_context_create([
        'http' => ['header' => "Cookie: session_token=$token"]
    ])
);
$connections = json_decode($response, true);

use reqwest::Client;

let client = Client::new();
let response = client
    .get("$BASE_URL/api/connections/active")
    .header("Cookie", format!("session_token={}", token))
    .send()
    .await?;

Response:

[
  {
    "id": "client_550e8400",
    "clientId": "client_550e8400",
    "userId": "user_123",
    "roomId": "ABC123",
    "presenterName": "John Doe",
    "isHost": true,
    "joinedAt": "2024-01-15T10:30:00Z",
    "connectionStatus": "connected"
  }
]

Kick User

Authentication Required

Forcefully disconnect a user from the system. Rate-limited to 30 requests per minute.

Endpoint: POST /api/connections/{id}/kick

Parameter	Type	Required	Description
`id`	path	Yes	Client ID to disconnect

curl -X POST "$BASE_URL/api/connections/client_550e8400/kick" \
  -b cookies.txt

const result = await $fetch('/api/connections/client_550e8400/kick', {
  method: 'POST',
  // session cookie (session_token) sent automatically same-origin
})

import requests

response = requests.post(
    "$BASE_URL/api/connections/client_550e8400/kick",
    headers={"Cookie": f"session_token={token}"}
)

req, _ := http.NewRequest("POST",
    "$BASE_URL/api/connections/client_550e8400/kick", nil)
req.Header.Set("Cookie", "session_token="+token)
resp, _ := http.DefaultClient.Do(req)

<?php
$response = file_get_contents(
    '$BASE_URL/api/connections/client_550e8400/kick',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Cookie: session_token=$token"
        ]
    ])
);

let response = client
    .post("$BASE_URL/api/connections/client_550e8400/kick")
    .header("Cookie", format!("session_token={}", token))
    .send()
    .await?;

Response:

{
  "success": true,
  "message": "Client disconnected"
}

Broadcast to Room

Authentication Required

Send a message to all clients in a room. Rate-limited to 30 requests per minute.

Endpoint: POST /api/connections/rooms/{roomId}/broadcast

Parameter	Type	Required	Description
`roomId`	path	Yes	Room ID to broadcast to
`message`	body	Yes	Message content

curl -X POST "$BASE_URL/api/connections/rooms/ABC123/broadcast" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"message":"Session ending in 5 minutes"}'

await $fetch('/api/connections/rooms/ABC123/broadcast', {
  method: 'POST',
  // session cookie (session_token) sent automatically same-origin
  body: { message: 'Session ending in 5 minutes' }
})

import requests

response = requests.post(
    "$BASE_URL/api/connections/rooms/ABC123/broadcast",
    headers={"Cookie": f"session_token={token}"},
    json={"message": "Session ending in 5 minutes"}
)

payload := map[string]string{"message": "Session ending in 5 minutes"}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
    "$BASE_URL/api/connections/rooms/ABC123/broadcast",
    bytes.NewBuffer(body))
req.Header.Set("Cookie", "session_token="+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)

<?php
$response = file_get_contents(
    '$BASE_URL/api/connections/rooms/ABC123/broadcast',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Content-Type: application/json\r\n" .
                       "Cookie: session_token=$token",
            'content' => json_encode(['message' => 'Session ending in 5 minutes'])
        ]
    ])
);

let response = client
    .post("$BASE_URL/api/connections/rooms/ABC123/broadcast")
    .header("Cookie", format!("session_token={}", token))
    .json(&json!({"message": "Session ending in 5 minutes"}))
    .send()
    .await?;

Response:

{
  "success": true,
  "message": "Message broadcast to 5 clients"
}

Close Room

Authentication Required

Close a room and disconnect all clients. Rate-limited to 5 requests per minute.

Endpoint: POST /api/connections/rooms/{roomId}/close

Parameter	Type	Required	Description
`roomId`	path	Yes	Room ID to close

curl -X POST "$BASE_URL/api/connections/rooms/ABC123/close" \
  -b cookies.txt

await $fetch('/api/connections/rooms/ABC123/close', {
  method: 'POST',
  // session cookie (session_token) sent automatically same-origin
})

import requests

response = requests.post(
    "$BASE_URL/api/connections/rooms/ABC123/close",
    headers={"Cookie": f"session_token={token}"}
)

req, _ := http.NewRequest("POST",
    "$BASE_URL/api/connections/rooms/ABC123/close", nil)
req.Header.Set("Cookie", "session_token="+token)
resp, _ := http.DefaultClient.Do(req)

<?php
$response = file_get_contents(
    '$BASE_URL/api/connections/rooms/ABC123/close',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Cookie: session_token=$token"
        ]
    ])
);

let response = client
    .post("$BASE_URL/api/connections/rooms/ABC123/close")
    .header("Cookie", format!("session_token={}", token))
    .send()
    .await?;

Response:

{
  "success": true,
  "message": "Room ABC123 closed, 5 clients disconnected"
}

Admin Operations Flow

Rate Limits

Endpoint	Requests / 60s	Tier
`/api/connections/active`	30	Standard
`/api/connections/{id}/kick`	30	Standard
`/api/connections/rooms/{roomId}/broadcast`	30	Standard
`/api/connections/rooms/{roomId}/close`	5	Strict

Limits are enforced per IP over a fixed 60-second window; exceeding one returns 429 until the window resets. There is no progressive block duration.

Licenses

License validation, activation, and device management API

WebRTC

TURN/STUN credentials for peer-to-peer video streaming