API

The REST API uses /api/v1 as the main prefix.

Successful responses use:

{ "success": true, "data": {} }

Error responses use:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Readable message",
    "detail": {}
  }
}

Main groups

Group	Prefix	Purpose
Auth	/api/v1/auth	Setup, login, session, password.
Configs	/api/v1/configs	Mesh config CRUD and overview.
Nodes	/api/v1/configs/{config_id}/nodes, /api/v1/nodes	Node CRUD, tags, keys, AWG random params.
Mesh	/api/v1/peer-links, /api/v1/configs/{config_id}/mesh	Peer links, validation, quick mesh.
Endpoint control	/api/v1/configs/{config_id}/nodes/{node_id}/endpoint	Runtime status, logs, MQTT control.
Tools	/api/v1/tools	Client downloads, bulk config packages, port forwarding.
Backups	/api/v1/backups	Snapshot create, list, export, restore, import, delete.
Settings	/api/v1/settings	UI, MQTT access settings, password.
System	/api/v1/system, /api/v1/events	Health, status, timezone, SSE.
MCP access	/api/v1/mcp-access	MCP tokens and audit logs.

Client binding uses /api/client/bind. EMQX internal authorization uses /api/internal/emqx/authz.

API Layers

WFM exposes multiple HTTP layers:

Layer	Prefix	Caller	Notes
Console API	/api/v1	Browser console and trusted external callers	Main business API. Usually requires administrator Bearer token.
Client API	/api/client	wfmctl bind	One-shot dynamic client binding. Does not use administrator session token.
Internal API	/api/internal	EMQX and internal components	Protected by an internal shared key.
Dev API	/api/v0	Local development and tests	Registered only when WFM_ENABLE_DEV_TEST_API=true.

The MCP HTTP endpoint is /mcp, but MCP tools should reuse the same service layer behind the console API.

Calling Conventions

Console APIs usually use:

Authorization: Bearer <admin-session-token>

Setup, login, health checks, and a small number of public endpoints are exceptions. Download endpoints may also accept short-lived file download tokens.

In production, the backend validates public origin and proxied Host. Browser requests must match allowed origins. CLI/curl requests without Origin are accepted only for the primary host. Development mode may relax these checks.

Client artifacts, bulk config packages, and snapshot exports may use 5-minute single-file download tokens. A download token is bound to one resource and cannot call other APIs.

Write APIs should follow the same order:

1. Validate input and permissions.
2. Mutate database state in a transaction.
3. Synchronize EMQX or dispatch MQTT if needed.
4. Publish SSE refresh events.
5. Return a result the frontend can show or use to refetch projections.