How to use the VPN Client API

The VPN Client runs as a daemon (on Linux or macOS) or as a service (on Windows) in the background of a PC and contains a lightweight web server that listens to requests on port 9250. The browser (portal.ixon.cloud) uses a REST api and a WebSocket to communicate with the VPN Client, for example to send a connect request to instruct the VPN Client to connect to a certain IXagent or IXrouter. The VPN Client can be seen as a connection tool between the application on your computer and the IXON Cloud and can setup a connection on behalf of the application, without the need to be privy to the technical details involved in creating a secure connection to a device. The REST api and WebSocket that the IXON Cloud uses are also available to 3rd party applications and opens up a myriad of possibilities.

SSL-certificate

The VPN Client REST API is available at https://localhost:9250.

The VPN Client installs its certificate into the system's store (on Windows), the system's keychain (on macOS) and to Firefox's certificate store (all Windows, macOS and Linux). Unfortunately, this implies that cURL may not trust the VPN Client's certificate automatically on Linux and will refuse to connect:
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html

This easiest solution is to pass --insecure to each cURL request, which will turn off certificate verification. It is also possible to instruct the VPN Client to serve its API with a user-provided certificate and use --cacert to verify the entire bundle. Please pick the most suitable approach for the target environment. For brevity either of these options will be omitted in the examples.

Discovery

The discovery serves as a starting point. Typically, a request to the discovery is made before the other endpoints are accessed: it serves as an entry point to 'discover' the other endpoints and their URLs. An example of this request is given below:

curl --request GET \
     --url https://localhost:9250 \
     --header 'Accept: application/json'

🚧

Authorization

Some endpoints require authorization with a bearer token from the APIv2. Please take a look at the article "How to use the APIv2" to see how to get a bearer token.

Currently this an example of the response you will receive.

{
  "links": [
    {
      "href": "https://localhost:9250/",
      "rel": "Discovery"
    },
    {
      "href": "https://localhost:9250/connect",
      "rel": "Connect"
    },
    {
      "href": "https://localhost:9250/disconnect",
      "rel": "Disconnect"
    },
    {
      "href": "https://localhost:9250/controller/closed",
      "rel": "ControllerClosed"
    },
    {
      "href": "https://localhost:9250/status",
      "rel": "Status"
    },
    {
      "href": "https://localhost:9250/configuration",
      "rel": "Configuration"
    },
    {
      "href": "https://localhost:9250/configuration/reset",
      "rel": "ConfigurationReset"
    },
    {
      "href": "wss://localhost:9250/",
      "rel": "StatusWebSocket"
    }
  ]
}

Controller Closed endpoint

One of the endpoints in the return above is the ControllerClosed endpoint. This endpoint has been created for possible future usage, but currently serves no purpose for the VPN Client API.