API Reference

Human-readable API docs for a device-first control plane.

Use this page when you want to understand what wg0 exposes today without reading raw YAML. The current model is devices first, nodes as memberships, relay assist at the network layer, and strict device-side control on the v2 surface.

OpenAPI 3.1 spec llms.txt Developers overview API health

Mental model

A device is one managed installation. A node is that device’s membership inside one network. Older automation can keep using node endpoints, but the managed UI and the newer API model now center on devices, memberships, endpoint history, mesh/peering state, and network-level relay policy.

Devices

Managed inventory, endpoint history, peerings, relay helpers, and membership-scoped settings.

Networks

Overlay or native. Relay assist is a network policy with never, auto, and always.

Nodes

Still real and still supported, but now best understood as memberships rather than the top-level management object.

Relay assist

Helps peers recover when direct peering is degraded. It is not a public web-exit and does not replace BYO Exit.

Authentication

Authorization: Bearer <JWT> — humans via dashboard and short-lived automation
Authorization: Bearer wg0_pat_... — long-lived automation / PATs
X-Device-Secret — v1 device-auth endpoints
X-Device-Secret + Wg0-Protocol-Version: 2 — strict v2 device and installation endpoints
X-Admin-Key — admin-only endpoints

PAT management remains JWT-only. A leaked PAT cannot mint successor credentials or revoke its siblings.

Accounts, membership context, and self-service

GET/api/v1/accounts/me — current account, plan, billing, and usage
GET/api/v1/accounts/me/memberships — accounts the caller belongs to
POST/api/v1/accounts/switch — switch active account context
GET/api/v1/accounts/device-profiles — access profiles
GET/api/v1/my-access — self-service member view
PATCH/api/v1/my-access/nodes/:id — self-service rename, delete, or VPN toggle
GET/api/v1/billing/status — billing readiness probe

Networks

GET/api/v1/networks — list networks with counts and traffic
POST/api/v1/networks — create overlay or native-LAN network
PATCH/api/v1/networks/:id — update network policy, including relay_mode
DELETE/api/v1/networks/:id — delete a network
POST/api/v1/networks/:id/provision — QR / server-side provisioning

relay_mode now applies to both overlay and native networks. On native networks it can temporarily help client-to-host reachability while NAT or firewall state settles.

Devices

GET/api/v1/devices — managed device inventory
GET/api/v1/devices/:id — one device and its memberships
PATCH/api/v1/devices/:id — device-level updates like display name and telemetry collection
GET/api/v1/devices/:id/endpoint-history — device-scoped endpoint timeline
GET/api/v1/devices/:id/peerings — peerings and relay-helper state
POST/api/v1/devices/:id/memberships — request another network membership
PATCH/api/v1/devices/:id/memberships/:node_id — update one membership
DELETE/api/v1/devices/:id/memberships/:node_id — remove one membership

Nodes and device protocol v1

GET/api/v1/nodes — compatibility list with presence and mesh metadata
PATCH/api/v1/nodes/:id — compatibility path for membership settings
POST/api/v1/nodes/:id/heartbeat — managed connector heartbeat
GET/api/v1/nodes/:id/config — fresh rendered config
POST/api/v1/nodes/:id/rotate-secret — rotate device secret

The v1 heartbeat now accepts more than just counters. Newer connectors can send installation_id, capabilities, host_lan_ip, and upstream_exit_health too.

Strict device protocol v2

POST/api/v2/devices/:id/state — report current state and receive desired state
GET/api/v2/devices/:id/state — desired-state poll
PATCH/api/v2/devices/:id/settings — strict device-side VPN toggle
GET/api/v2/installations/:id/state — installation inventory
POST/api/v2/installations/:id/memberships/:request_id/fulfill — fulfill pending membership

This is the forward-looking connector surface. Use it for strict capability-aware state convergence and device-side settings.

Relay assist and BYO Exit

Relay assist and BYO Exit solve different problems:

Relay assist helps managed peers communicate when direct peer-to-peer is degraded.
BYO Exit determines where internet egress happens for a host and any clients routing through it.

Even when a client is in VPN-through-host mode and relay assist is active, internet egress still happens on the host node or its configured upstream exit — not on the relay’s public IP.

Quick start

Base URL: https://connect.wg0.io

# 1. Log in and get a bearer token TOKEN=$(curl -sf -X POST https://connect.wg0.io/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","password":"correct horse battery staple"}' \ | jq -r .access_token) # 2. Create a native network curl -sf -X POST https://connect.wg0.io/api/v1/networks \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name":"PRISMA MANAGEMENT", "network_type":"native", "native_gateway_subnet":"10.255.16.0/24", "native_host_tunnel_ip":"10.255.16.70", "native_client_start":"10.255.16.200", "native_client_end":"10.255.16.220" }' # 3. Turn relay assist on for that network curl -sf -X PATCH https://connect.wg0.io/api/v1/networks/$NET_ID \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"relay_mode":"auto"}' # 4. Inspect the managed devices view curl -sf -H "Authorization: Bearer $TOKEN" \ https://connect.wg0.io/api/v1/devices | jq .