API Reference

Understand how WakeLink combines REST endpoints, WebSocket relay sessions, and EWSP end-to-end encryption into one control plane.

Note
WakeLink exposes three complementary surfaces: the FastAPI REST API under /api/v1, a relay WebSocket endpoint at /wss, and the EWSP encrypted payload format used inside those sessions.

Base endpoints

SurfaceEndpointPurpose
REST API/api/v1Account, agent, release, and admin HTTP endpoints.
WebSocket relay/wssLong-lived relay sessions for firmware agents and interactive clients.
OpenAPI JSON/api/openapi.jsonMachine-readable schema generated from FastAPI routes.
Interactive viewers/api/docs /api/redocSwagger UI and ReDoc consoles served by the relay.
curl https://wakelink-project.org/api/v1/auth/config
wscat -c wss://wakelink-project.org/wss

Authentication model

WakeLink separates account authentication from agent routing and from end-to-end encryption. Human-operated clients use the account-level wl_… token for REST calls, firmware agents use per-agent wla_… tokens for relay authentication, and EWSP derives per-session encryption keys from the separate agent_token (E2E Secret) shared only between client and agent. All tokens are stored as SHA-256 hashes on the relay. 

POST /api/v1/auth/login
{ "username": "alice", "password": "***", "totp_code": "123456" }

→ { "access_token": "***", "user": { "api_token": "wl_..." } }

POST /api/v1/auth/session
Authorization: Bearer ***

→ { "session_token": "wls_...", "expires_at": "2026-06-11T12:00:00Z" }
Tip
Use /auth/token/rotate when a wl_… account token may be compromised. Use /agents/{'{'}agent_id{'}'}/rotate-token when you need to revoke a single agent relay token without affecting the rest of the account.

Core surfaces

→ REST API — Register users, create agents, rotate tokens, inspect stats. → WebSocket Protocol — Client/auth, ping/pong, relay forwarding. → EWSP Wire Format — Handshake, session IDs, encrypted payload framing. → OpenAPI Spec — Live schema, request models, client bindings.

OTA and admin

The same API surface also exposes operational helpers for firmware rollouts and observability. Firmware clients can call GET /releases/check to discover the latest published release, while operators can query health and admin statistics endpoints when running the full stack. 

GET /api/v1/releases/check?channel=stable&version=1.0.0
Authorization: Bearer ***

GET /api/v1/admin/stats
Authorization: Bearer ***

Next steps