Updated November 1st, 2014.
hello
Returns supported API version, valid actions and (optional) authentication hashes. (READ)
Resource URL
https://example.com/vpngui/?action=hello&protoversion=2013.06&username=foobar
Parameters
| action | hello |
| protoversion |
Comma delimited list of API versions supported by the client. The API version is encoded as YYYY.MM.
Example value: “2013.06” |
| username | The username the client will later use to log in.
As we will see below in the reply, the server can require the client to send a salted hash of the password instead of plain text. In order to return the right salt value, the server might need the username. |
Response parameters
| action |
Current action being executed.
Current value: hello |
| protoversion |
The API version used by the server.
Example value: “2013.06” In general the provisioning server will decide to use the newest version of the protocol supported by the client, or return an error. |
| actions |
Array of valid actions.
Example value: {‘hello’, ‘login’, ‘info’, ‘list’} |
| authentication – optional |
Array of supported authentication hashes and their (optional) salt. If no authentication parameter is returned, VPNGUI will send the password in plain text. Valid hash values are ‘md5’, ‘sha1’, ‘sha256’, and ‘sha512.’
Example value: {‘hash’:’sha1′} or {‘hash’:’sha1′, ‘salt’:’abcdefg’}. If the server responds with ‘sha1’ as hash and ‘abcdefg’ as salt, the client will send in the login command sha1(‘abcdefg<actual password>’). |
| contact – optional |
a UTF-8 string that is the email address logs should be ‘shared’ to when clicking the share button in the VPNGUI Log Viewer. This can be used to easily create a ticket in the provider’s ticketing system when the user encounters a problem.
Example value: ticket@example.com |
| iconrhs – optional |
a UTF-8 string with the value “yes” or “no“. When set to “yes“, the icon of the application will be displayed on the right hand side of the status bar (OSX only). The user can override the value.
Default value: no |
Response status codes
To differentiate between a misconfigured webserver sending a HTTP Status 403 error and protocol defined 403 errors, we add an X-Status-Reason: user forbidden header.
| 200 | OK | |
| 400 | Bad Request | protocol version mismatch or missing parameter(s) |
| 403 | Forbidden | username is unknown. The server might wish not to reveal this information and pretend the username was fine. That is, send a 200 OK status. |
Example request
GET /vpngui/?action=hello&protoversion=2013.06&username=foobar HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"action": "hello",
"protoversion": "2013.6",
"actions": [
"hello",
"info",
"license",
"list",
"login",
"msg",
"refresh"
],
"authentication": {
"hash": "sha1",
"salt": "er84nxz77kxmnjykd10u6rmeahybr6ro"
}
}
Example PHP code
header("Content-Type: application/json;charset=UTF-8");
header("Cache-Control: no-store");
header("Pragma: no-cache");
$r = array(
"action" => "hello",
"protoversion" => "2013.6",
"actions" => array('hello', 'info', 'license', 'list'),
"authentication" => array(
'hash'=>'sha1',
'salt'=>'er84nxz77kxmnjykd10u6rmeahybr6ro')
);
echo json_encode($r, JSON_PRETTY_PRINT);
Example request 2
GET /vpngui/?action=hello&protoversion=2013.06&username=quuz HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response 2
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
X-Status-Reason: user unknown
Cache-Control: no-store
Pragma: no-cache
login
Returns access and refresh tokens and an access token expiry interval (CREATE access token). Authentication works on basis of OAuth 2.0 Resource Owner Password Credentials Grant
Resource URL
https://example.com/vpngui/?
Parameters
| action | login |
| protoversion |
Comma delimited list of API versions supported by the client. The API version is encoded as YYYY.MM.
Example value: “2013.06” |
| grant_type | Current value: password |
| username |
The username
Example value: aUserName |
| password |
Plain text password or hashed password based on previously received authentication requirements. For example, when the provisioning server requires the client to send a hashed password using sha1 and salt “foobar”, the client computes sha1(‘foobar<actual password>’).
Example value: 2b5893d1c40b26da7593bd5324297fab67a01211 |
Response parameters
| action |
Current action being executed.
Current value: login |
| protoversion |
The API version used by the server.
Example value: “2013.06” In general the provisioning server will decide to use the newest version of the protocol supported by the client, or return an error. |
| access_token |
An opaque string that must be used for future requests that require authentication.
Example value: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 The exact details of the token are up to the provisioning server. The client treats it as an opaque data blob. |
| token_type | Current value: Bearer |
| expires_in |
Interval in seconds representing the time the access token is valid. The client can use this field to decide when it should refresh the access token.
Example value: 3600 |
| refresh_token |
An opaque string that must be used to refresh an expired access token.
Example value: 00195ec7f337ef93fd66be33ddf21eada |
Response status codes
To differentiate between a misconfigured webserver sending a HTTP Status 403 error and protocol defined 403 errors, we add an X-Status-Reason: user forbidden header.
| 200 | OK | |
| 400 | Bad Request | protocol version mismatch, missing or incomplete parameter(s) |
| 403 | Forbidden | username and password combination is invalid. This could mean that the username does not exist or is not allowed to log in, or that the accompanying password is incorrect. |
Example request
POST /vpngui/? HTTP/1.1
Host: example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
grant_type=password&username=aUserName&password=2b5893d1c40b26da7593bd5324297fab67a01211&protoversion=2013.06&action=login
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "00195ec7f337ef93fd66be33ddf21eada",
"action": "login",
"protoversion": "2013.06"
}
Example request 2
POST /vpngui/? HTTP/1.1
Host: example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
grant_type=password&username=quuz&password=2b5893d1c40b26da7593bd5324297fab67a01211&protoversion=2013.06&action=login
Example response 2
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
X-Status-Reason: user forbidden
Cache-Control: no-store
Pragma: no-cache
list
Returns list of servers the authenticated user is authorized to access. (READ)
Resource URL
https://example.com/vpngui/?action=list&protoversion=2013.06
Parameters
| action | list |
| protoversion |
Comma delimited list of API versions supported by the client. The API version is encoded as YYYY.MM.
Example value: “2013.06” |
Response parameters
| action |
Current action being executed.
Current value: list |
| protoversion |
The API version used by the server.
Example value: “2013.06” In general the provisioning server will decide to use the newest version of the protocol supported by the client, or return an error. |
| server | Array of server ID strings. |
| update – optional |
Interval in seconds representing the time the client should wait before refreshing the server list (in order not to miss out on updates while logged in). When this value is not provided VPNGUI assumes the default value. Valid values range from 1 to 268000.
Example value: 3600 When the client fails to update its list of servers after the update interval has expired due to network issues or otherwise, it will keep retrying the request every 30 seconds. |
Response status codes
To differentiate between a misconfigured webserver sending a HTTP Status 403 error and protocol defined 403 errors, we add an X-Status-Reason: user forbidden header.
| 200 | OK | |
| 400 | Bad Request | protocol version mismatch, missing or incomplete parameter(s) |
| 403 | Forbidden | No access token provided, access token has expired, token is not an access token (i.e., it is a refresh token), or user is not allowed access. |
Example request
GET /vpngui/?action=list&protoversion=2013.06 HTTP/1.1
Host: example.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"action": "list",
"server": [
"id",
"id2",
"id3"
],
"update": "1800",
"protoversion":"2013.06"
}
Example PHP code
header("Content-Type: application/json;charset=UTF-8");
header("Cache-Control: no-store");
header("Pragma: no-cache");e
$r = array(
"action" => "hello",
"server" => array('id', 'id2', 'id3'),
"update" => "1800"
);
echo json_encode($r, JSON_PRETTY_PRINT);
Example request 2
GET /vpngui/?action=list&protoversion=2013.06 HTTP/1.1
Host: example.com
Authorization:
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response 2
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Example request 3
GET /vpngui/?action=list&protoversion=2013.06 HTTP/1.1
Host: example.com
Authorization: Bearer invalidToken123
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response 3
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
X-Status-Reason: user forbidden
Cache-Control: no-store
Pragma: no-cache
info
Returns an array of server descriptions. (READ)
Resource URL
https://example.com/vpngui/?action=info&protoversion=2013.06&id=id2
Parameters
| action | info |
| protoversion |
Comma delimited list of API versions supported by the client. The API version is encoded as YYYY.MM.
Example value: “2013.06” |
| serverid |
Comma delimited list of server IDs you want detailed information on. The information includes server properties, the connections the server provides, and the connection properties. |
Response parameters
| action |
Current action being executed.
Current value: info |
| protoversion |
The API version used by the server.
Example value: “2013.06” In general the provisioning server will decide to use the newest version of the protocol supported by the client, or return an error. |
| info | Array of servers and their properties. |
Response status codes
To differentiate between a misconfigured webserver sending a HTTP Status 403 error and protocol defined 403 errors, we add an X-Status-Reason: user forbidden header.
| 200 | OK | |
| 400 | Bad Request | protocol version mismatch, missing or incomplete parameter(s) |
| 403 | Forbidden | No access token provided, access token has expired, token is not an access token (i.e., it is a refresh token), or user is not authorized to access a server ID. |
| 404 | Not Found | A server ID was not valid |
Server description
A server is an object consisting of the following keys:
| id | a UTF-8 string of up to 30 characters. Is not allowed to start with an ‘*’ (asterisk). | |
| name | a UTF-8 string of up to 50 characters | |
| group | optional | a UTF-8 string of up to 20 characters |
| preferred | optional |
a UTF-8 string with the value “yes” or “no“. When there are multiple servers and one is marked preferred, then the preferred server is selected by default in the client (as opposed the first server in the list). In case there are multiple preferred servers, one is selected at random.
Default value: no |
| status | array consisting of server state and server description | |
| state | a UTF-8 string that can be one of the following: “online“, “offline“, or “problematic“. This means a server is online and usable, offline and not usable, online but may pose usability problems, respectively. | |
| description | optional | a UTF-8 string of up to 150 characters describing the state of the server |
| timestamp | a UTF-8 string representing the current time measured in seconds since the UNIX Epoch in UTC | |
| update | a UTF-8 string representing a time interval measured in seconds until the client should ask for an update on the server details | |
| descriptions | optional | array consisting of a description language and server description |
| lang | optional | IETF language tag as defined in RFC 5646 |
| description | a UTF-8 string of up to 150 characters describing the server in general | |
| attributes | optional | array of attribute objects. An attribute object key and value key-value pairs . Can be used in the future to tag the server with certain properties. |
| key | a UTF-8 string of up to 20 characters | |
| value | a UTF-8 string of up to 50 characters | |
| connections | an array of connections |
Connection description
A connection is an object consisting of the following keys:
| type | a UTF-8 string describing the type of connection. Currently supported type is: “openvpn“ | |
| name | optional |
a UTF-8 string of up to 50 characters
The name should be user friendly. When a server has multiple connections, this name is shown to select a specific connection. When no name is provided the connection id is displayed instead. |
| id |
a UTF-8 string of up to 30 characters
A connection ID must be unique with respect to the server it belongs to. That is, it doesn’t have to be globally unique. |
|
| config | Object consisting of the keys secrets and properties, which are an array of Connection Secrets and an array of Connection Properties, respectively. | |
| obfsproxy | optional | array consisting of a host(name), port, and obfspec that can be used by obfsproxy to tunnel this connections.
Note: tunneling a connection through obfsproxy implies that all remote endpoints in the configuration (i.e., where the VPN server software is listening for incoming connections) are discarded when the tunnel is used. Instead, the obfsproxy host and port will function as remote endpoint (which in turn redirects traffic to the proper remote endpoint). |
| host | a UTF-8 string of up to 64 characters | |
| port | a UTF-8 string of up to 5 characters representing the port number | |
| transport | a UTF-8 string with the value “obfs2“, “scramblesuit“, “obfs3“, or “b64“. | |
| psk | optional | a UTF-8 string representing a pre-shared key for transport modes “obfs2” and “scramblesuit“. It is optional for “obfs2” and limited to 64 characters when provided. It is mandatory for “scramblesuit” and must be a base32 encoded string of 20 characters. |
| authentication | optional | array consisting of username and password
This can be used to prefill connection authentication details instead of asking the user to provide them. |
| user | a UTF-8 string of up to 64 characters | |
| password | a UTF-8 string of up to 64 characters |
Connection Secret description
Some connections require certificates or keys stored in files. They can be transmitted using this object. The object consists of the following keys:
| filename | name of the file. For example, OpenVPN has the configuration property secret <file> that denotes the path to a file holding a static key. filename must not include a path. | |
| data | base64 encoded contents of the file |
Connection Property description
Connection properties are described using Connection Property objects. The object consists of the following keys:
| key | property name | |
| value | property (default) value | |
| hidden | optional |
a UTF-8 string with the value “yes” or “no“. Meaning that when a user displays the connection properties through the preferences pane, the values are hidden by default or not. A user can always decide to show hidden properties.
Default value: yes |
| rule | optional | Property Rule object. Rules can be used to describe which values are valid. If left out, the user is free to change it to anything (possibly breaking the configuration). Rules can describe a range of integers, a regular expression the value has to match to, or a set of strings the user can choose from. A property can have at most only one rule |
Range rule
| type | a UTF-8 string with the value “range“ | |
| from | a UTF-8 string representing the integer where the range starts. Valid values are -2147483648 up to 2147483647. Default value must be equal or larger than this value. | |
| to | a UTF-8 string representing the integer where the range stop (inclusive). Valid values are -2147483648 up to 2147483647. Default value must be equal or less than this value. |
Regular Epression rule
| type | a UTF-8 string with the value “regex“ | |
| expression | a UTF-8 string representing the regular expression against which the value must match. Note that default value must match as well. The expression string length is limited at 255 characters. |
Set rule
| type | a UTF-8 string with the value “set“ | |
| set | an array of UTF-8 strings. Note that the default value must be equal to one of these strings. Strings have max length of 255 characters. |
Example request
GET /vpngui/?action=info&protoversion=2013.06&id=id2,id3 HTTP/1.1
Host: example.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"action": "info",
"protoversion": "2013.06",
"info": [
{
"id": "id2"
"name": "server name",
"group": "servergroup",
"status": {
"state": "online",
"description": "A description of the state of this server"
},
"timestamp": "1382992884",
"update": "7200",
"descriptions": [
{
"lang": "en_US",
"description": "Description"
},
{
"lang": "nl_NL",
"description": "Beschrijving"
},
{
"description": "Default description with lowest priority. Chosen when no specific language is chosen in GUI"
}
],
"attributes": [
{
"key": "key",
"value": "value"
},
{
"key": "key2",
"value": "value2"
}
],
"connections": [
{
"type": "openvpn",
"name": "name",
"id": "openvpn",
"config": {
"secrets": [
{
"filename": "name",
"data": "file content"
},
{
"filename": "anothername"
"data": "file content"
}
],
"properties": [
{
"key": "mtu",
"value": "1400",
"hidden": "yes",
"rule":
{
"type": "range",
"from": "0",
"to": "1500"
}
}
]
}
},
{
"type": "openvpn",
"name": "name2",
"id": "openvpn2",
"config": {
"secrets": [
{
"filename": "name",
"data": "file content"
}
],
"properties": [
{
"key": "otherkey",
"value": "othervalue",
"hidden ": "no",
"rules": [
{
"type": "set",
"set": [
"item",
"foo",
"bar"
]
}
]
}
]
}
}
]
},
{
"id": "id3"
"name": "another server name",
"group": "servergroup",
"status": {
"state": "offline",
"description": "Server is under maintenance. Back in an hour."
},
"timestamp": "1382992884",
[...]
}
]
}
Example request 2
GET /vpngui/?action=info&protoversion=2013.06&id=id2,nonexistentid HTTP/1.1
Host: example.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
Content-Type: application/json
Accept: application/json
User-Agent: com.wanwire.vpngui/0.6.2 (Mac OS X 10.8.5)
Accept-Language: en_US
Example response 2
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
refresh
Returns a new access token based on a (valid) refresh token. (CREATE)
Resource URL
https://example.com/vpngui/?
Parameters
| action | license |
| protoversion |
Comma delimited list of API versions supported by the client. The API version is encoded as YYYY.MM.
Example value: “2013.06” |
| refresh_token | opaque string obtained with the login request |
Response parameters
| action |
Current action being executed.
Current value: refresh |
| protoversion |
The API version used by the server.
Example value: “2013.06” In general the provisioning server will decide to use the newest version of the protocol supported by the client, or return an error. |
| access_token |
An opaque string that must be used for future requests that require authentication.
Example value: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 The exact details of the token are up to the provisioning server. The client treats it as an opaque data blob. |
| token_type | Current value: Bearer |
| expires_in |
Interval in seconds representing the time the access token is valid. The client can use this field to decide when it should refresh the access token.
Example value: 3600 |
| refresh_token |
An opaque string that must be used to refresh an expired access token.
Example value: 00195ec7f337ef93fd66be33ddf21eada |
Response status codes
To differentiate between a misconfigured webserver sending a HTTP Status 403 error and protocol defined 403 errors, we add an X-Status-Reason: user forbidden header.
| 200 | OK | |
| 400 | Bad Request | protocol version mismatch, missing or incomplete parameter(s) |
| 403 | Forbidden | No refresh token provided, refresh token is invalid, token is not a refresh token (i.e., it is an access token), or user is not allowed access. |
Example request
POST /vpngui/? HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
refresh_token=00195ec7f337ef93fd66be33ddf21eada&protoversion=2013.06&action=refresh
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "00195ec7f337ef93fd66be33ddf21eada",
"action": "refresh"
}