WireGuard Endpoints
WireGuard tunnel management including client connections, peer management, and transport tunneling on OrbMesh servers.
Connect (Client)
Establishes a WireGuard tunnel connection. The client sends its public key and receives the server's public key, an assigned IP address, and full tunnel configuration.
/wireguard/connectEstablish a WireGuard tunnel connection with key exchange and IP assignment
Device Token Required
This endpoint requires a device token obtained from OrbNET's device authorization flow, not a user JWT. See the OrbMesh Authentication section for details.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
publicKey | string | Required | The client's WireGuard public key (base64-encoded). Generate a keypair locally before calling this endpoint. |
exitServerId | string | Optional | Target exit server ID for bridge (multi-hop) mode. When set, this server acts as the bridge entry point and forwards traffic to the specified exit server. |
force_direct | boolean | Optional | When true, forces a direct connection even if SmartConnect recommends bridge mode. Defaults to false. |
Code Examples
curl -X POST https://198.51.100.1:8443/wireguard/connect \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"publicKey": "CLIENT_PUBLIC_KEY_BASE64"
}'Response
{
"success": true,
"publicKey": "CLIENT_PUBLIC_KEY_BASE64",
"serverPublicKey": "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
"ip": "10.8.0.42/32",
"gateway": "10.8.0.1",
"serverEndpoint": "198.51.100.1:51820",
"dns": ["10.8.0.1", "1.1.1.1"],
"allowedIPs": ["0.0.0.0/0", "::/0"],
"mtu": 1420,
"keepalive": 25
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired device token"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the connection was established |
publicKey | string | Echo of the client's public key |
serverPublicKey | string | Server's WireGuard public key for the peer configuration |
ip | string | Assigned tunnel IP address with subnet mask |
gateway | string | Gateway IP address for the tunnel |
serverEndpoint | string | Server endpoint in host:port format for the WireGuard peer |
dns | string[] | DNS servers to configure on the tunnel interface |
allowedIPs | string[] | IP ranges to route through the tunnel |
mtu | integer | Maximum Transmission Unit (default 1420) |
keepalive | integer | Persistent keepalive interval in seconds (default 25) |
Disconnect (Client)
Terminates an active WireGuard connection and removes the client peer from the server.
/wireguard/disconnectDisconnect the current WireGuard tunnel and remove the peer
Code Examples
curl -X POST https://198.51.100.1:8443/wireguard/disconnect \
-H "Authorization: Bearer DEVICE_TOKEN"Response
{
"success": true,
"message": "Disconnected successfully"
}Server Status (Internal)
Returns the current WireGuard interface status, including the server public key and active peer count. This endpoint is used internally by OrbNET for monitoring.
/wireguard/statusGet WireGuard server interface status and peer count
Internal Endpoint
This endpoint is called by OrbNET for server monitoring and orchestration. It is not intended for client applications. Access requires an internal API key.
Code Examples
curl -X GET https://198.51.100.1:8443/wireguard/status \
-H "X-API-Key: INTERNAL_API_KEY"Response
{
"success": true,
"publicKey": "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
"peerCount": 142
}HTTP Tunnel
Tunnels WireGuard traffic over HTTP for environments where direct UDP is blocked. The client sends WireGuard packets encapsulated in HTTP POST requests, enabling traversal through HTTP proxies and protocol-filtering firewalls.
/wireguard/tunnelHTTP tunnel transport for WireGuard protocol obfuscation
When to Use HTTP Tunnel
Use this transport when direct WireGuard UDP connections are blocked by a firewall or DPI system. The HTTP tunnel wraps WireGuard packets in standard HTTPS traffic, making them indistinguishable from normal web requests.
Code Examples
# The HTTP tunnel is typically used by OrbVPN client apps.
# Raw usage sends encapsulated WireGuard packets:
curl -X POST https://198.51.100.1:8443/wireguard/tunnel \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @wireguard_packet.binWebSocket Tunnel
Upgrades the connection to a WebSocket for continuous bidirectional WireGuard packet transport. This is the preferred tunnel method for proxy traversal as it maintains a persistent connection.
/wireguard/wsWebSocket tunnel for continuous WireGuard packet transport through proxies
WebSocket Upgrade
This endpoint requires a WebSocket upgrade handshake. The client must send standard WebSocket upgrade headers along with the Bearer token. Once upgraded, WireGuard packets are exchanged as binary WebSocket frames.
Code Examples
# WebSocket connections require a WebSocket client.
# Using websocat for demonstration:
websocat -b \
-H "Authorization: Bearer DEVICE_TOKEN" \
wss://198.51.100.1:8443/wireguard/wsAdd Peer (Internal)
Adds a WireGuard peer to the server interface. Called by OrbNET during user provisioning and connection orchestration.
/wireguard/add-peerAdd a WireGuard peer to the server interface (called by OrbNET)
Internal Management Endpoint
This endpoint is called exclusively by OrbNET for peer lifecycle management. Do not call it from client applications. Use /wireguard/connect for client connections instead.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userUuid | string | Required | The unique user identifier from OrbNET. |
publicKey | string | Required | The client's WireGuard public key (base64-encoded). |
allowedIPs | string | Required | Allowed IP ranges for the peer (e.g., "10.8.0.42/32"). |
assignedIP | string | Required | The IP address assigned to this peer within the tunnel subnet. |
endpoint | string | Optional | The client's public endpoint in host:port format. Optional for roaming clients. |
noKeepalive | boolean | Optional | When true, disables persistent keepalive for this peer. Defaults to false. |
Code Examples
curl -X POST https://198.51.100.1:8443/wireguard/add-peer \
-H "X-API-Key: INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userUuid": "usr_abc123",
"publicKey": "CLIENT_PUBLIC_KEY_BASE64",
"allowedIPs": "10.8.0.42/32",
"assignedIP": "10.8.0.42",
"noKeepalive": false
}'Response
{
"success": true,
"message": "Peer added successfully"
}Remove Peer (Internal)
Removes a WireGuard peer from the server interface. Called by OrbNET during user disconnection or session cleanup.
/wireguard/remove-peerRemove a WireGuard peer from the server interface (called by OrbNET)
Internal Management Endpoint
This endpoint is called exclusively by OrbNET. Client applications should use /wireguard/disconnect instead.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userUuid | string | Required | The unique user identifier whose peer should be removed. |
Code Examples
curl -X POST https://198.51.100.1:8443/wireguard/remove-peer \
-H "X-API-Key: INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userUuid": "usr_abc123"
}'Response
{
"success": true,
"message": "Peer removed successfully"
}Related Endpoints
- Health & Monitoring -- Server health and protocol status
- VLESS -- VLESS protocol endpoints
- OrbConnect -- OrbConnect tunnel management
- Bridge Mode -- Multi-hop bridge connections
- Protocol Mimicry -- Traffic disguise profiles