Skip to content

Server HTTP API

Jump to bottom
Anton Liashkevich edited this page Jan 14, 2026 · 3 revisions

WallGuard Server API

Endpoints

1. Enable traffic monitoring

POST to /wallguard/api/v1/enable_traffic_monitoring

Enables or disables traffic monitoring for a specific device.

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "enable": <boolean>
}

Where

  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • enable: boolean flag to enable or disable the feature.

Responds with 200 OK if the request has been processed successfully.

2. Enable telemetry monitoring

POST to /wallguard/api/v1/enable_telemetry_monitoring

Enables or disables telemetry monitoring for a specific device.

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "enable": <boolean>
}

Where

  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • enable: boolean flag to enable or disable the feature.

Responds with 200 OK if the request has been processed successfully.

3. Enable configuration monitoring

POST to /wallguard/api/v1/enable_config_monitoring

Enables or disables configuration monitoring for a specific device.

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "enable": <boolean>
}

Where

  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • enable: boolean flag to enable or disable the feature.

NOTE:
This endpoint should be called for WallGuard clients of types either PfSense or OPNsense. Other type of devices do not support configuration monitoring as of August 2025.

Responds with 200 OK if the request has been processed successfully.

4. Request Remote Access Session

POST to /wallguard/api/v1/remote_access

Request remote access session of the requested type

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "session_type": "<string>",
    "data": {
        "service_id": "<string>"
    }
}

Where

  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • session_type: session type. Possible values: ssh, tty or ui.
  • service_id: service id. Required only for ui sessions.

Respons with a unique token:

{
    "session_token": "<string>"
}

5. Terminate Remote Access Session

DELETE to /wallguard/api/v1/remote_access

Terminate remote access session and all open associated tunnels.

{
    "session": "<string>",
}

Where

  • session: Remote Access Session token (device_remote_access_sessions table)

6. SSH session proxy

WebSocket to /wallguard/gateway/ssh

Use this endpoint to establish tunneled SSH session into a device.

This endpoint requires the server URL to include the session token as a subdomain.
Format:

ws://${SESSION_TOKEN}.${SERVER_DOMAIN}/wallguard/gateway/ssh

For example, If your session token is 0xdeadbeef and the server domain is nullnet.com, the request URL should be:

ws://0xdeadbeef.nullnet.com/wallguard/gateway/ssh

7. TTY session proxy

WebSocket to /wallguard/gateway/tty

Use this endpoint to establish tunneled TTY session into a device.

This endpoint requires the server URL to include the session token as a subdomain.
Format:

ws://${SESSION_TOKEN}.${SERVER_DOMAIN}/wallguard/gateway/tty

For example, If your session token is 0xdeadbeef and the server domain is nullnet.com, the request URL should be:

ws://0xdeadbeef.nullnet.com/wallguard/gateway/tty

8. UI Proxy

The server also acts as a regular HTTP proxy that proxies HTTP into a connected device.

You would need to obtain a session_token for a ui session and then format the URL according to the following format:

http://${SESSION_TOKEN}.${SERVER_DOMAIN}/

For example, If your session token is 0xdeadbeef and the server domain is nullnet.com, the request URL should be:

http://0xdeadbeef.nullnet.com/

9. Authorize Device

POST to /wallguard/api/v1/authorize_device

Authorized a pending device.

{
    "device_id": "<string>"
}

Responds with 200 OK if the request has been processed successfully.

10. Create Filter Rule:

POST to /wallguard/rule/filter

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "rule": {
        "disabled": <boolean>,
        "policy": "<string>",
        "protocol": "<string>",
        "source_inversed": <boolean>,
        "source_port": "<string>",
        "source_addr": "<string>",
        "source_type": "<string>",
        "destination_inversed": <boolean>,
        "destination_port": "<string>",
        "destination_addr": "<string>",
        "destination_type": "<string>",
        "description": "<string>",
        "interface": "<string>",
        "id": <number>,
        "order": <number>,
        "associated_rule_id": "<string>"
    }
}

Where

  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • disabled: Rule is enabled or disabled by default.
  • policy: Rule policy. pass, reject or deny.
  • protocol: Target protocol. Should be formatted {L3PROTO}/{L4PROTO}, where:
    • L3PROTO values: inet (ipv4), inet6 (ipv6) or inet46 (Both)
    • L4PROTO L4 protocol.
    • Example: inet6/tcp
  • source_inversed: Defined is matching source info should be negated.
  • source_port: Source port, port values (comma sepparated) or port range (8080-9090).
  • source_addr: Source IP address ot network
  • source_type: Type of source data info, e.g. ip address or network
  • destination_inversed: Defined is matching destination info should be negated.
  • destination_port: Destination port, port values (comma sepparated) or port range (8080-9090).
  • destination_addr: Destination IP address ot network
  • destination_type: Type of destination data info, e.g. ip address or network
  • description: Rule description
  • interface: Assosiated device interface
  • id: Unique identifier
  • order: Rules order in the list of rules
  • associated_rule_id: Value of associated_rule_id of an assosiated NAT rule.

Responds with 200 OK if the request has been processed successfully.

NOTE: The server will send a command to the designated client, however, if won't respond with an error if rule creation actually fails.

11. Create NAT Rule

POST to /wallguard/rule/nat

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "rule": {
        "disabled": <boolean>,
        "protocol": "<string>",
        "source_inversed": <boolean>,
        "source_port": "<string>",
        "source_addr": "<string>",
        "source_type": "<string>",
        "destination_inversed": <boolean>,
        "destination_port": "<string>",
        "destination_addr": "<string>",
        "destination_type": "<string>",
        "description": "<string>",
        "interface": "<string>",
        "redirect_ip": "<string>",
        "redirect_port": <number>,
        "order": <number>,
        "associated_rule_id": "<string>"
    }
}

Where

  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • disabled: Rule is enabled or disabled by default.
  • protocol: Target protocol. Should be formatted {L3PROTO}/{L4PROTO}, where:
    • L3PROTO values: inet (ipv4), inet6 (ipv6) or inet46 (Both)
    • L4PROTO L4 protocol.
    • Example: inet6/tcp
  • source_inversed: Defines if matching source info should be negated.
  • source_port: Source port, port values (comma separated) or port range (8080-9090).
  • source_addr: Source IP address or network.
  • source_type: Type of source data, e.g. IP address or network.
  • destination_inversed: Defines if matching destination info should be negated.
  • destination_port: Destination port, port values (comma separated) or port range (8080-9090).
  • destination_addr: Destination IP address or network.
  • destination_type: Type of destination data, e.g. IP address or network.
  • description: Rule description.
  • interface: Associated device interface.
  • redirect_ip: IP address of the redirect target.
  • redirect_port: Port number of the redirect target.
  • order: Rule order in the list of rules.
  • associated_rule_id: Identifier of the associated filter rule.

Responds with 200 OK if the request has been processed successfully.

NOTE: The server will send a command to the designated client; however, it will not respond with an error if rule creation actually fails.

12. Create Alias

POST to /wallguard/alias

{
    "device_id": "<string>",
    "instance_id": "<string>",
    "alias": {
        "type": "<string>",
        "name": "<string>",
        "value": "<string>",
        "description": "<string>"
    }
}
  • device_id: Device Id. (devices table)
  • instance_id: Instance Id. (device_instances table)
  • type: Alias type (e.g. host, network, port).
  • name: Unique name of the alias.
  • value: Alias value, such as an IP address, network, or port list.
  • description: Description of the alias.

Responds with 200 OK if the request has been processed successfully.

NOTE: The server will send a command to the designated client; however, it will not respond with an error if alias creation actually fails.

Clone this wiki locally