VPN API

The VPN API exposes Eden Gateway interlays over standard WireGuard clients. It is available when eden-service is built with the vpn feature.

VPN routes do not grant endpoint access by themselves. They expose an interlay listener and may lower the maximum data-plane permissions available through that listener. The peer's resolved user or agent subject must still be authorized through endpoint RBAC or ELS.

Networks

Create VPN Network

http
POST /api/v1/vpn/networks
Authorization: Bearer <token>
Content-Type: application/json
json
{
  "name": "prod-database-vpn",
  "interface_name": "wg-eden-prod",
  "address_cidr": "10.77.0.0/24",
  "listen_port": 51820,
  "eden_node_uuid": "00000000-0000-0000-0000-000000000001",
  "server_endpoint": "eden-prod.example.com:51820",
  "server_public_key": "<wireguard-server-public-key>",
  "server_private_key_ref": "secret://eden/vpn/prod"
}

Eden stores a server private-key reference, not private-key bytes.

List VPN Networks

http
GET /api/v1/vpn/networks
Authorization: Bearer <token>

Delete VPN Network

http
DELETE /api/v1/vpn/networks/{network_uuid}
Authorization: Bearer <token>

Peers

Create VPN Peer

http
POST /api/v1/vpn/networks/{network_uuid}/peers
Authorization: Bearer <token>
Content-Type: application/json
json
{
  "name": "devon-laptop",
  "subject": "devon@example.com",
  "public_key": "<wireguard-client-public-key>",
  "tunnel_ip": null
}

When tunnel_ip is null, Eden allocates the next available peer address inside the network CIDR.

List VPN Peers

http
GET /api/v1/vpn/networks/{network_uuid}/peers
Authorization: Bearer <token>

Update VPN Peer

http
PATCH /api/v1/vpn/peers/{peer_uuid}
Authorization: Bearer <token>
Content-Type: application/json
json
{
  "name": "devon-new-laptop",
  "public_key": "<new-wireguard-client-public-key>",
  "tunnel_ip": "10.77.0.22"
}

Revoke VPN Peer

http
DELETE /api/v1/vpn/peers/{peer_uuid}
Authorization: Bearer <token>

Render VPN Client Config

http
GET /api/v1/vpn/peers/{peer_uuid}/config
Authorization: Bearer <token>

Eden returns a standard WireGuard config. AllowedIPs contains only routes the peer subject can use through endpoint RBAC or ELS.

Routes

Create VPN Route

http
POST /api/v1/vpn/networks/{network_uuid}/routes
Authorization: Bearer <token>
Content-Type: application/json
json
{
  "interlay": "prod-mysql-vpn",
  "listener_id": "mysql",
  "vpn_ip": "10.77.0.3",
  "eden_node_uuid": "00000000-0000-0000-0000-000000000001",
  "max_data_perms": "r"
}

vpn_ip must be inside the VPN network CIDR and must match the selected interlay listener bind_host. max_data_perms is a ceiling and cannot elevate the subject beyond RBAC or ELS.

List VPN Routes

http
GET /api/v1/vpn/networks/{network_uuid}/routes
Authorization: Bearer <token>

Delete VPN Route

http
DELETE /api/v1/vpn/routes/{route_uuid}
Authorization: Bearer <token>

Endpoint Node Placement

VPN route creation requires the route Eden node to be registered for the interlay endpoint and in an available or degraded connection status.

http
GET /api/v1/endpoints/{endpoint}/nodes
PUT /api/v1/endpoints/{endpoint}/nodes/{eden_node_uuid}

Related Docs

Last updated: July 10, 2026