mvpg/docs/API.md

API Reference

Overview

The VPN Gateway provides a RESTful API for managing VPN connections and configuration.

Base URL: http://<gateway-ip>:5000

Authentication

Currently, the API does not require authentication for local network access. For production use, consider implementing API keys or JWT tokens.

Endpoints

System Status

GET /api/status

Get current VPN and system status.

Response:

{
  "connected": true,
  "provider": "mullvad",
  "server": "se-sto-wg-001",
  "ip": "185.65.134.123",
  "location": "Stockholm, Sweden",
  "uptime": "2h 34m",
  "killswitch_active": true
}

Provider Management

GET /api/providers

List available providers.

Response:

{
  "providers": ["mullvad", "custom", "imported"],
  "current": "mullvad"
}

POST /api/provider/{provider}

Switch to a different provider.

Parameters:

• provider: Provider name (mullvad|custom|imported)

Response:

{
  "success": true,
  "provider": "custom"
}

Server Management

GET /api/servers

Get available servers for current provider.

Response:

{
  "servers": {
    "Sweden": {
      "Stockholm": [
        {
          "hostname": "se-sto-wg-001",
          "ipv4": "185.65.134.123",
          "type": "WireGuard",
          "provider": "Mullvad"
        }
      ]
    }
  },
  "provider": "mullvad"
}

Connection Management

POST /api/connect

Connect to VPN server.

Request Body:

{
  "server": "se-sto-wg-001"
}

Response:

{
  "success": true
}

POST /api/disconnect

Disconnect from VPN.

Response:

{
  "success": true,
  "message": "Disconnected - No internet (killswitch active)"
}

Custom Server Management

POST /api/custom/add

Add a custom WireGuard server.

Request Body:

{
  "name": "my-vps",
  "endpoint": "1.2.3.4:51820",
  "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
  "private_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy=",
  "address": "10.0.0.2/32",
  "dns": "1.1.1.1,1.0.0.1",
  "allowed_ips": "0.0.0.0/0,::/0",
  "location": "Germany"
}

Response:

{
  "success": true
}

DELETE /api/custom/remove/{name}

Remove a custom server.

Parameters:

• name: Server name

Response:

{
  "success": true
}

Import Configuration

POST /api/import

Import a WireGuard configuration.

Request Body:

{
  "name": "imported-config",
  "config": "[Interface]\nPrivateKey = xxx\n..."
}

Response:

{
  "success": true
}

Utility

GET /api/keypair

Generate a new WireGuard keypair.

Response:

{
  "private_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
  "public_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy="
}

GET /health

Health check endpoint.

Response:

healthy

Error Responses

All endpoints may return error responses:

{
  "success": false,
  "error": "Error message here"
}

Common HTTP status codes:

• 200: Success
• 400: Bad request
• 404: Not found
• 500: Internal server error

WebSocket Events (Future)

Planned WebSocket support for real-time updates:

const ws = new WebSocket('ws://gateway-ip:5000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.payload);
};

Events:

• status_change: VPN connection status changed
• server_update: Server list updated
• security_alert: Security issue detected

Example Usage

cURL

# Get status
curl http://gateway-ip:5000/api/status

# Connect to server
curl -X POST http://gateway-ip:5000/api/connect \
  -H "Content-Type: application/json" \
  -d '{"server":"se-sto-wg-001"}'

# Add custom server
curl -X POST http://gateway-ip:5000/api/custom/add \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server",
    "endpoint": "1.2.3.4:51820",
    "public_key": "xxx..."
  }'

Python

import requests

# API base URL
base_url = "http://gateway-ip:5000"

# Get status
response = requests.get(f"{base_url}/api/status")
status = response.json()
print(f"Connected: {status['connected']}")

# Connect to server
response = requests.post(
    f"{base_url}/api/connect",
    json={"server": "se-sto-wg-001"}
)
if response.json()["success"]:
    print("Connected successfully")

JavaScript

// Get status
fetch('http://gateway-ip:5000/api/status')
  .then(response => response.json())
  .then(data => console.log('Status:', data));

// Connect to server
fetch('http://gateway-ip:5000/api/connect', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    server: 'se-sto-wg-001'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log('Connected');
  }
});

Rate Limiting

API endpoints are rate-limited:

• General endpoints: 10 requests/second
• Connection endpoints: 5 requests/second

Headers returned:

• X-RateLimit-Limit: Request limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

Future Enhancements

Planned API features:

• JWT authentication
• GraphQL endpoint
• Metrics endpoint (Prometheus format)
• Bulk operations
• Configuration backup/restore
• Traffic statistics
• Connection history