donaldzou/WGDashboard
1
1
Fork 0
mirror of https://github.com/donaldzou/WGDashboard.git synced 2024-11-10 08:53:51 +08:00
Code Issues Projects Releases Packages Wiki Activity
WGDashboard/docs/api-documents.md
Donald Zou e68257d6c9 Updated some documentations
2024-08-15 23:20:29 -04:00

12 KiB
Raw Permalink Blame History

📖 API Document for WGDashboard

Version: v4.0

Created by: Donald Zou

🔑 How to use API Key?

Create API Key

  1. To request an API Key, simply login to your WGDashboard, go to Settings, scroll to the very bottom. Click the switch on the right to enable API Key.
  2. Click the blur Create button, set an expiry date you want or never expire, then click Done.

Use API Key

  • Simply add wg-dashboard-apikey with the value of your API key into the HTTP Header.
fetch('http://server:10086/api/handshake', {
    headers: {
       'content-type': 'application/json',
        'wg-dashboard-apikey': 'insert your api key here'
    },
    method: "GET"
})

API Endpoints

Handshake to Server

This endpoint is designed for a simple handshake when using API key to connect. If status is true that means

Request

GET /api/handshake

Response

200 - OK

{
    "data": null,
    "message": null,
    "status": true
}

401 - UNAUTHORIZED

{
    "data": null,
    "message": "Unauthorized access.",
    "status": false
}

Notice: this 401 response will return at all endpoint if your API Key or session is invalid.

Validate Authentication

This endpoint if needed for non-cross-server access. This will check if the cookie on the client side is still valid on the server side.

Request

GET /api/validateAuthentication

Response

200 - OK

Session is still valid

{
    "data": null,
    "message": null,
    "status": true
}

Session is invalid

{
    "data": null,
    "message": "Invalid authentication.",
    "status": false
}

Authenticate

This endpoint is dedicated for non-cross-server access. It is used to authenticate user's username, password and TOTP

Request

POST /api/authenticate

Body Parameters
{
    "username": "admin",
    "password": "admin",
    "totp": "123456"
}
Parameter Type
username string
password string
totp string

Response

200 - OK

If username, password and TOTP matched

{
    "data": null,
    "message": null,
    "status": true
}

If username, password or TOTP is not match

{
    "data": null,
    "message": "Sorry, your username, password or OTP is incorrect.",
    "status": false
}

Sign Out

To remove the current session on server side

Request

GET /api/signout

Response

200 - OK

{
    "data": null,
    "message": null,
    "status": true
}

Get WireGuard Configurations

To get all WireGuard configurations in /etc/wireguard

Request

GET /api/getWireguardConfigurations

Response

200 - OK

{
    "data": [
        {
            "Address": "10.200.200.1/24",
            "ConnectedPeers": 0,
            "DataUsage": {
                "Receive": 0.1582,
                "Sent": 2.1012999999999997,
                "Total": 2.2595
            },
            "ListenPort": "51820",
            "Name": "wg0",
            "PostDown": "iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o enp0s1 -j MASQUERADE;",
            "PostUp": "iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE;",
            "PreDown": "",
            "PreUp": "",
            "PrivateKey": "8DsSMli3okgUx5frKbFQ0fMW5ZMyqyxOdOW7+g21L18=",
            "PublicKey": "GQlGi8QJ93hWY7L2xlJyh+7S6+ekER9xP11T92T0O0Q=",
            "SaveConfig": true,
            "Status": false
        }
    ],
    "message": null,
    "status": true
}

Add WireGuard Configuration

Add a new WireGuard Configuration

Request

POST /api/addWireguardConfiguration

Body Parameters
{
    "ConfigurationName": "wg0",
    "Address": "10.0.0.1/24",
    "ListenPort":  51820,
    "PrivateKey": "eJuuamCgakVs2xUZGHh/g7C6Oy89JGh7eE2jjEGbbFc=",
    "PublicKey":  "3Ruirgw9qNRwNpBepkiVjjSe82tY+lDZr6WaFC4wO2g=",
    "PresharedKey": "GMMLKWdJlgsKVoR26BJPsNbDXyfILL+x1Nd6Ecmn4lg=",
    "PreUp":  "",
    "PreDown": "iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o enp0s1 -j MASQUERADE;",
    "PostUp":  "iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE;",
    "PostDown": ""
}
Parameter Type
ConfigurationName string
Address string
ListenPort int
PrivateKey string
PublicKey string
PresharedKey string
PreUp string
PreDown string
PostUp string
PostDown string

Response

200 - OK

If everything is good

{
    "data": null,
    "message": null,
    "status": true
}

If the new configuration's ConfigurationName is already existed

{
    "data": null,
    "message": "Already have a configuration with the name \"wg0\"",
    "status": false
}

If the new configuration's ListenPort is used by another configuration

{
    "data": null,
    "message": "Already have a configuration with the port  \"51820\"",
    "status": false
}

If the new configuration's Address is used by another configuration

{
    "data": null,
    "message": "Already have a configuration with the address  \"10.0.0.1/24\"",
    "status": false
}

Toggle WireGuard Configuration

To turn on/off of a WireGuard Configuration

Request

GET /api/toggleWireguardConfiguration/?configurationName=

Query String Parameter
Parameter Type
configurationName string

Response

200 - OK

If toggle is successful, server will return the current status in status: true or false indicating if the configuration is up or not.

{
    "data": true,
    "message": null,
    "status": true
}

If the configurationName provided does not exist

{
    "data": null,
    "message": "Please provide a valid configuration name",
    "status": false
}

Get WGDashboard Configuration

Get the WGDashboard Configuration, such as dashboard_theme...

Request

GET /api/getDashboardConfiguration

Response

200 - OK

{
    "data": {
        "Account": {
            "enable_totp": false,
            "password": "some hashed value :(",
            "totp_verified": false,
            "username": "admin"
        },
        "Database": {
            "type": "sqlite"
        },
        "Other": {
            "welcome_session": false
        },
        "Peers": {
            "peer_display_mode": "grid",
            "peer_endpoint_allowed_ip": "0.0.0.0/0",
            "peer_global_dns": "1.1.1.1",
            "peer_keep_alive": "21",
            "peer_mtu": "1420",
            "remote_endpoint": "192.168.2.38"
        },
        "Server": {
            "app_ip": "0.0.0.0",
            "app_port": "10086",
            "app_prefix": "",
            "auth_req": true,
            "dashboard_api_key": true,
            "dashboard_refresh_interval": "5000",
            "dashboard_sort": "status",
            "dashboard_theme": "dark",
            "version": "v4.0",
            "wg_conf_path": "/etc/wireguard"
        }
    },
    "message": null,
    "status": true
}

Update WGDashboard Configuration Item

Update the WGDashboard Configuration one at a time

Request

POST /api/updateDashboardConfigurationItem

Body Parameters
{
    "section": "Server",
    "key": "dashboard_theme",
    "value": "dark"
}
Parameter Type
section string Each section in the wg-dashboard.ini
key string Each key/value pair under each in the wg-dashboard.ini
value string Value for this key/value pair

Response

200 - OK

If update is success

{
    "data": true,
    "message": null,
    "status": true
}

If update failed

{
    "data": true,
    "message": "Message related to the error will appear here",
    "status": false
}

Get WGDashboard API Keys

Get a list of active API key in WGDashboard

Request

GET /api/getDashboardAPIKeys

Response

200 - OK

If API Key function is enabled and there are active API keys

If ExpiredAt is null, that means this API key will never expire

{
    "data": [
        {
            "CreatedAt": "2024-08-15 00:42:31",
            "ExpiredAt": null,
            "Key": "AXt1x3TZMukmA-eSnAyESy08I14n20boppSsknHOB-Y"
        },
        {
            "CreatedAt": "2024-08-14 22:50:44",
            "ExpiredAt": "2024-08-21 22:50:43",
            "Key": "ry0Suo0BrypSMzbq0C_TjkEcgrFHHj6UBZGmC2-KI2o"
        }
    ],
    "message": null,
    "status": true
}

If API key function is disabled

{
    "data": null,
    "message": "Dashboard API Keys function is disabled",
    "status": false
}

Add WGDashboard API Key

Add a new API Key in WGDashboard

Request

POST /api/newDashboardAPIKey

Body Parameters
{
    "neverExpire": false,
    "ExpiredAt": "2024-12-31 16:00:00"
}
Parameter Type
neverExpire bool If this is false, please specify a date in ExpiredAt
ExpiredAt string If neverExpire is true, this can be omitted. Format is YYYY-MM-DD hh:mm:ss.

Response

200 - OK

If success, it will return the latest list of API Keys

{
  "data": [
    {
      "CreatedAt": "2024-08-15 00:42:31",
      "ExpiredAt": null,
      "Key": "AXt1x3TZMukmA-eSnAyESy08I14n20boppSsknHOB-Y"
    },
    {
      "CreatedAt": "2024-08-14 22:50:44",
      "ExpiredAt": "2024-12-31 16:50:43",
      "Key": "ry0Suo0BrypSMzbq0C_TjkEcgrFHHj6UBZGmC2-KI2o"
    }
  ],
  "message": null,
  "status": true
}

If API key function is disabled

{
    "data": null,
    "message": "Dashboard API Keys function is disabled",
    "status": false
}

Endpoint

Description

Request

GET

Response

200 - OK

{
    "data": true,
    "message": null,
    "status": true
}