Spokes API

This section covers the HTTP API available in the Spokes server which is currently in beta. The API can be used along side the webhooks provided to dynamically monitor and manage tunnels and requests being processed by the system.

The APIs can be used by external systems to manage critical authentication keys like registration tokens.

Tunnels can be queried to monitor their state, traffic rules, remote client configurations and bandwidth statistics. Users can be imported into the system so that Spokes administrators can create and link tunnels with users from another domain, e.g. your other systems.

Request Headers

All requests to the API must include the following headers in each request sent to the server. If the server doesn't see both of these header fields with the respective values set in the example below, it will be rejected by the Spokes server.

Content-type: application/json
Accept: application/json

The admin API will only accept request encoded in JSON and will send all responses in JSON.

Authentication

Clients using the API need to authentication prior to using any of the other APIs defined in this document. Authenticated is performed once. On success the Spokes server will upgrade the web session of the client to authenticated. Future API calls that maintain cookies will remain authenticated.

Cookies expire after 24 hours or when the client calls the logout endpoint.

Auth

The auth endpoint requires an administrative token be used and passed in using the key parameter. Admin tokens can be created in the Spokes dashboard.

`POST/api/admin/v1.0/auth`

Parameters

key	An API key can be created in the Spokes dashboard. Visit the API section.

Request

{
    "key": "34a7fb347ef9dc7238788eaa3e1bd954ca3dd7ffc0dfd42901de90f9a52ed663"
}

Response

Parameters

status	boolean	Indicates success of the operation. If the session is destroyed true is returned. If there are errors or the session never exited or expired earlier, false is returned.
message	string	Information about the operation.
error	string	Error is populated when status is set to false.

{
    "status": true,
    "message": "user authenticated",
    "error": ""
}

Logout

Destroys the web session for the client.

`GET/api/admin/v1.0/logout`

Response

Parameters

status	boolean	Indicates success of the operation. If the session is destroyed true is returned. If there are errors or the session never exited or expired earlier, false is returned.
message	string	More information about the operation.

{
    "status": true,
    "message": "session closed"
}

Licenses

These endpoints will help license monitor and manage licenses. Clients can request information about the currently used license such the max tunnels and when it expires.

Info

Retrieve information about the current license. When the status value is set to false that will indicate that no valid license is available on the server. This state will prevent new tunnels from being created and existing tunnels from re-connecting to the server.

The maximum number of active tunnels and the time the license expires is returned when a valid license is present.

`GET/api/admin/v1.0/license/info`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
maxTunnels	integer	Maximum number of tunnels that can be active at any given time.
expires	string	Timestamp for when the license will expire.

Example Response

{
  "status": true,
  "error": "",
  "maxTunnels": 1000,
  "expires": "2021-01-26T22:16:08.899460303Z"
}

Tokens

There are several types of tokens maintained by the Spokes in the backend: API, registration, and authentication tokens. Registration tokens are used as a secret key by clients to authenticate themselves to the Spokes server and configure a new tunnel. That operation will result in a new tunnel and an authentication token for the tunnel.

Authentications are an item used to identify and authenticate a tunnel. They are not managed by administrators and so there are no endpoints for managing them. Instead we manage the tunnels.

Registration tokens can be used to deploy a fleet devices or applications that can configure themselves automatically and connect to Spokes.

Create

Registration tokens are used by clients to create tunnels and request authenticaton tokens. By default registrations are not set to active, but can be optionally set to active in the request.

The token is returned when the operation is a success.

`POST/api/admin/v1.0/token/registration/create`

Parameters

description	string	A description for the registration token
active	boolean	Tokens are not active by default, override this by specifying flag

Request

{
    "description": "smart refrigerator factory token",
    "active": true
}

Response

{
  "status": true,
  "error": "",
  "token": {
    "id": "d6c52563f18f47ae9714b3a5a972fe0e",
    "created": "2021-01-26T22:16:08.899460303Z",
    "modified": "2021-01-26T22:16:08.899460388Z",
    "active": true,
    "description": "smart refrigerator factory token",
    "value": "..."
  }
}

List

List all of the registration tokens in the system. A detailed description of the token data type is available at the end of this document.

`GET/api/admin/v1.0/token/registration/list`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
tokens	Token	List of registration tokens.

Example Response

{
  "status": true,
  "error": "",
  "tokens": [
    {
      "id": "814df88c3c664d4e90425c065057faa3",
      "created": "2020-10-28T22:51:58.485820183Z",
      "modified": "2020-10-28T22:51:58.485820289Z",
      "active": true,
      "description": "shorter token",
      "value": "..."
    },
    {
      "id": "d6c52563f18f47ae9714b3a5a972fe0e",
      "created": "2021-01-26T22:16:08.899460303Z",
      "modified": "2021-01-26T22:16:08.899460388Z",
      "active": true,
      "description": "this tunnel is a test",
      "value": "..."
    }
  ]
}

Delete

This operation will delete the registration token on the backend.

`POST/api/admin/v1.0/token/registration/delete`

Parameters

tokenID

Unique ID for the registration token

Request

{
  "tokenID": "d6c52563f18f47ae9714b3a5a972fe0e"
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`

{
  "status": true,
  "error": ""
}

Edit

This operation allows the caller to update the description and active state for the registration token. You will need to carry over existing values, such as the description, even if you intend to just modify another property such as active.

`POST/api/admin/v1.0/token/registration/edit`

Parameters

tokenID	string	Unique ID for the registration token
description	string	An update description
active	boolean	Boolean flag that will set registration active (usable) or not

Request

{
  "tokenID": "d6c52563f18f47ae9714b3a5a972fe0e"
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`

{
  "status": true,
  "error": ""
}

Tunnels

In this section we describe the various endpoints for retrieving information about the tunnels that are being managed by the Spokes server. These operation include retrieving basic tunnel information, detailed information about individual tunnels and shutting tunnels down.

Tunnel objects via the active, online, search or list-all endpoints will be paginated when there are more than 50 objects result. Page objects are stored in the links property of tunnel responses and includes the page number, number of objects in the page, and the URL that can be used to retrieve the listing of objects for the page. The page object is described in my detail in data types section of this document.

Tunnel properties are described in more detail in data types section of this document.

Active Tunnels

Active tunnels are those that are in-use but not necessarily online. Effectively these are tunnels that have not been shut down (deleted).

`GET/api/admin/v1.0/tunnel/list/active`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
total	integer	Total number of links across paginated results.
tunnels	Tunnel	List of active tunnels.
links	TunLinks	1-n objects returned with URL to retrieve paginated responses.

Example Response

{
  "status": true,
  "error": "",
  "tunnels": [
    {
      "id": "669462bbfd344addba295215e25bea46",
      "userID": "eebd6a453f454420b4bbd11ae037d5b8",
      "created": "2020-10-30T01:19:38.001079502Z",
      "lastActive": "2021-01-27T20:09:29.272137844Z",
      "state": 2,
      "uptime": 11609,
      "bandwidth": {
        "daily": 0,
        "monthly": 103014490
      },
      "name": "unnamed",
      "hostname": "windows-10-01.packetdemo.com",
      "address": "123.4.5.6",
      "version": "v0.10.5",
      "os": "windows",
      "arch": "amd64"
    },
    {
      "id": "d5ce2469fe56458aa796f209980a13e4",
      "userID": "0ad89e85d46844d08c3b63e4550a96f1",
      "created": "2021-01-15T20:30:54.344469319Z",
      "lastActive": "2021-01-27T20:09:43.118743093Z",
      "state": 2,
      "uptime": 11655,
      "bandwidth": {
        "daily": 4348,
        "monthly": 1832554220
      },
      "name": "unnamed",
      "hostname": "rasp-pi-123.packetdemo.com",
      "address": "123.4.5.7",
      "version": "v0.10.7",
      "os": "linux",
      "arch": "amd64"
    },
  ]
}

Online Tunnels

Online tunnels are currently connected to the Spokers server.

`GET/api/admin/v1.0/tunnel/list/online`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
total	integer	Total number of links across paginated results.
tunnels	Tunnel	List of tunnels that are currently online and connected to the Spokes server.
links	TunLinks	1-n objects returned with URL to retrieve paginated responses.

Example Response

{
  "status": true,
  "error": "",
  "totals": 2,
  "tunnels": [
    {
      "id": "669462bbfd344addba295215e25bea46",
      "userID": "eebd6a453f454420b4bbd11ae037d5b8",
      "created": "2020-10-30T01:19:38.001079502Z",
      "lastActive": "2021-01-27T20:09:29.272137844Z",
      "state": 2,
      "uptime": 11609,
      "bandwidth": {
        "daily": 0,
        "monthly": 103014490
      },
      "name": "unnamed",
      "hostname": "windows-10-01.packetdemo.com",
      "address": "123.4.5.6",
      "version": "v0.10.5",
      "os": "windows",
      "arch": "amd64"
    },
    {
      "id": "d5ce2469fe56458aa796f209980a13e4",
      "userID": "0ad89e85d46844d08c3b63e4550a96f1",
      "created": "2021-01-15T20:30:54.344469319Z",
      "lastActive": "2021-01-27T20:09:43.118743093Z",
      "state": 2,
      "uptime": 11655,
      "bandwidth": {
        "daily": 4348,
        "monthly": 1832554220
      },
      "name": "unnamed",
      "hostname": "rasp-pi-123.packetdemo.com",
      "address": "123.4.5.7",
      "version": "v0.10.7",
      "os": "linux",
      "arch": "amd64"
    },
  ]
}

List All

This operation will return all tunnels that Spokes has stored in its database. It will include tunnels that have been shut down.

`GET/api/admin/v1.0/tunnel/list`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
total	integer	Total number of links across paginated results.
tunnels	Tunnel	List of all tunnels in the database.
links	TunLink	1-n objects returned with URL to retrieve paginated responses.

Example Response

{
  "status": true,
  "error": "",
  "totals": 10,
  "tunnels": [
    ...
  ]
}

Search Tunnels

This operation will use the term and filters for OS, architecture, and version to search across all active tunnels. The term will be compared as a string and sub-string against the tunnel name, hostname and IP address. The OS, architecture and version will be applied are filtering criteria and are used in conjuction with each other.

`POST/api/admin/v1.0/tunnel/search`

Parameters

term	string	A search term that is used for string and sub-string search for tunnel name, hostname, or host IP address.
os	string	Filter based on operating system: windows, macos, linux, freebsd.
arch	string	Filter based on architecture: amd64, i386, arm32, arm64.
version	string	Filter based on client version, examples: v0.10.3, v1.0.22.

Request

Search for a hostname.

{
  "term": "host-123.spokes.example.com",
}

Search for v1.0.0 Linux clients running on amd64 architecture.

{
  "os": "linux",
  "version": "v1.0.0",
  "arch": "amd64"
}

Search clients with host IP address of 1.2.3.4.

{
  "term": "1.2.3.4"
}

Search clients with the substring testing in the name of the tunnel.

{
  "term": "testing"
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
total	integer	Total number of links across paginated results.
tunnels	Tunnel	List of all tunnels in the database.
links	TunLink	1-n objects returned with URL to retrieve paginated responses.

Example Response

{
  "status": true,
  "error": "",
  "totals": 10,
  "tunnels": [
    ...
  ]
}

Paginated Tunnel Results

This operation will return a paginated tunnel result. When a tunnel listing: active, online, search or list-all, is performed the results will be broken up into pages no more than 50 objects and cached for 720seconds. A UID is created for each page and passed as a parameter to this request.

The result will be an object identical or other tunnel listing endpoints. It will not include any values in the links property since it is part of a set of paged tunnel objects.

`GET/api/admin/v1.0/tunnel/page/:UID`

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
total	Total number of links across paginated results.
tunnels	List of all tunnels in the database.
links	1-n objects returned with URL to retrieve paginated responses.

Example Response

{
  "status": true,
  "error": "",
  "totals": 10,
  "tunnels": [
    ...
  ]
}

Detailed Information

This endpoint requires an ID to identify the tunnel and will return all of the information associated to the tunnel and the active HTTP/S and TCP traffic rules that were last active when the tunnel connected.

Each time a tunnel and requests traffic relays it will record valid relays in the database. These relays will be updated each time a tunnel connects. This API will only return the last set of active traffic relays.

`GET/api/admin/v1.0/tunnel/info/:ID`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
tunnel	Tunnel	The tunnel specified by ID.

Example Response

{
  "status": true,
  "error": "",
  "tunnel": {
    "id": "669462bbfd344addba295215e25bea46",
    "userID": "eebd6a453f454420b4bbd11ae037d5b8",
    "created": "2020-10-30T01:19:38.001079502Z",
    "lastActive": "2021-01-27T16:56:41.50859125Z",
    "state": 2,
    "uptime": 45,
    "bandwidth": {
      "daily": 0,
      "monthly": 103014490
    },
    "name": "unnamed",
    "hostname": "windows.spokes.borak.co",
    "address": "100.1.17.138",
    "version": "v0.10.5",
    "os": "windows",
    "arch": "amd64",
    "https": [
      {
        "id": "3ef7ab59c41c453cbee46b0ce4f7f6d3",
        "userID": "eebd6a453f454420b4bbd11ae037d5b8",
        "tunID": "669462bbfd344addba295215e25bea46",
        "active": true,
        "available": true,
        "secure": true,
        "domainName": "windows-10-01.packetdemo.com",
        "bandwidth": {
          "daily": 0,
          "monthly": 102993728
        }
      },
    ],
    "ports": [
      {
        "id": "ceaf246c08884d69b61acccaf004ee27",
        "userID": "eebd6a453f454420b4bbd11ae037d5b8",
        "tunID": "669462bbfd344addba295215e25bea46",
        "active": true,
        "availabe": false,
        "protocol": 1,
        "port": 22262,
        "bandwidth": {
          "daily": 0,
          "monthly": 0
        },
        "label": ""
      }
    ]
  }
}

Shutdown Tunnel

This endpoint requires an ID to identify the tunnel and will shut down the tunnel. If the tunnel is online it's session will be terminated as well.

`GET/api/admin/v1.0/tunnel/shutdown/:ID`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`

Example Response

{
    "status": true,
    "error": ""
}

Authentication Token

This endpoint requires an ID to identify the tunnel and will return the authentication token for the tunnel.

One example for the-case of this endpoint is to recover this value for a tunnel.

`GET/api/admin/v1.0/tunnel/auth/:ID`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
token	Token	The authentication token associated to the tunnel.

Example Response

{
  "status": true,
  "error": "",
  "token": {
    "id": "d6c52563f18f47ae9714b3a5a972fe0e",
    "created": "2021-01-26T22:16:08.899460303Z",
    "modified": "2021-01-26T22:16:08.899460388Z",
    "active": true,
    "description": "",
    "value": "..."
  }
}

Configuration

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

The configuration is fetched from the client over the tunnel. This configuration reflects how the client is configured and includes attributes such as the operating system, client version and architecture, in addition to traffic rules.

`GET/api/admin/v1.0/tunnel/config/:ID`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Error message set by server when status is set to `false`
config	TunConfiguration	The remote client configuration

Example Response

{
  "status": true,
  "error": "",
  "config": {
    "version": "v0.10.5",
    "os": "windows",
    "arch": "amd64",
    "https": [
      {
        "domain": "windows-10-01.packetdemo.com",
        "secure": true,
        "webRoot": "C:\\Packetriot\\www",
        "useLetsEnc": true,
        "redirect": true
      }
    ],
    "ports": [
      {
        "port": 22262,
        "destination": "",
        "dstPort": 0
      }
    ]
  }
}

Create / Update HTTP Site

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

The HTTP site rule will overwrite an existing traffic rule that shares the same domain name, e.g. sub.example.com. Otherwise, it will create a new site the traffic forwarding options provided.

The request can include many different parameters. Some parameters cannot be mixed such as: destination/http/tls and upstreamURL. The former three parameters are used to determine a destination for HTTP and/or TLS traffic. UpstreamURL defines a destination as well but in an URL format.

A TLS example is turning on (setting true) letsEncrypt and also specifying a custom certificate with ca and privateKey.

One last example is mixing password with basicHttpAuth. The former is used for passphrase logins presented to actual user and another

This HTTP site changes are sent to the client and will be negotiated between the it and the Spokes server. If the server rejects to relay the requested HTTP traffic then status will be set to false.

`POST/api/admin/v1.0/tunnel/traffic/http/update/:ID`

The request requires a field called sites and is composed of a list of objects using the definition below.

Parameters

domain	string	Domain for HTTP/S traffic requested, e.g. example.com
secure	boolean	True indicates https (443) traffic is also requested.
upstreamURL	string
webroot	string
destination	string	Forward traffic to this host or IP address.
port	integer	Port on destination to forward HTTP (plain-text) traffic to. Note, TLS is terminated in the Packetriot client when using Let's Encrypt or custom certificates, so incoming client traffic can be HTTPS.
tls	integer	Port to forward TLS traffic, transparent TLS proxying.
useLetsEnc	boolean	Boolean flag to indicate lets-encrypt for TLS certificates.
ca	string	Base64 encoded value of custom certificate authority, the CA must be PEM encoded.
privateKey	string	Base64 encoded value of private key, the key must be based on RSA and also be PEM encoded.
redirect	boolean	Boolean that indicates whether HTTP is redirected to HTTPS.
password	string	Salted-hash of password to permit traffic.
basicHttpAuth	string	Salted-hash of user:password (HTTP basic auth) to permit traffic.
rewriteHost	string	Rewrite the Host header with this value.
redirectURL	string	URL that all incoming requests are redirected to.
insecureUpstream	boolean	Flag indicates if an insecure TLS certificate is accepted when traffic is reverse-proxied.
firewall	array of Firewall objects	List of firewall rules that are applied to the incoming traffic to this HTTP site, traffic can be allowed or dropped.

Request

Create HTTP site traffic for plain-text:

{
  "sites": [{
    "domain": "host-123.spokes.example.com",
    "destination": "127.0.0.1",
    "port": 8080,
    "redirect": false
  }]
}

Create HTTP site traffic using Lets Encrypt for TLS and secure (HTTPS) redirection:

{
  "sites": [{
    "domain": "host-123.spokes.example.com",
    "destination": "127.0.0.1",
    "port": 8080,
    "useLetsEnc": true,
    "redirect": true
  }]
}

Create HTTP site traffic using an upstream URL:

{
  "sites": [{
    "domain": "host-123.spokes.example.com",
    "upsteamURL": "http://127.0.0.1:8080",
    "useLetsEnc": true,
    "redirect": true
  }]
}

Create HTTP site traffic blocking incoming traffic from an IPv4 network:

{
  "sites": [{
    "domain": "host-123.spokes.example.com",
    "upsteamURL": "http://127.0.0.1:8080",
    "useLetsEnc": true,
    "redirect": true,
    "firewall": [
      {
        "sequence": 1,
        "action": "drop",
        "network": "25.1.2.0/24"
      }
    ]
  }]
}

Create HTTP site traffic that allows incoming traffic from all hosts on two IPv4 networks and one specific IP address:

{
  "sites": [{
    "domain": "host-123.spokes.example.com",
    "upsteamURL": "http://127.0.0.1:8080",
    "useLetsEnc": true,
    "redirect": true,
    "firewall": [
      {
        "sequence": 1,
        "action": "allow",
        "network": "25.1.2.0/24"
      },
      {
        "sequence": 2,
        "action": "allow",
        "network": "128.64.1.0/24"
      },
      {
        "sequence": 3,
        "action": "allow",
        "network": "9.18.24.123/32"
      }
    ]
  }]
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

HTTP site update success:

{
  "status": true,
}

Spokes could not connect to tunnel to submit site traffic request:

{
  "status": false,
  "error": "connection EOF",
  "message": "Failure establishing connection to client over tunnel."
}

Additional Notes

This section provides some additional notes for the use of this endpoint.

Using Custom Certificates

When creating HTTP/S sites and using custom certificates, it's important to use site-specific certificates and not fullchain certificates. A fullchain certificate will include all parent certificates, hence fullchain. The client program expects only a site-specific certificate and will return errors when it doesn't receive one.

In addition, the certificate and private key properties in the create/update HTTP/S site endpoint expects both values to be Base-64 encoded. The certificate and private key are expected to be PEM encoded, which means that are Base-64 encoded. However, PEM includes newlines and to avoid escaping and creating difficult messages to inspect when debugging, we require that these PEM encoded keying material are Base64-encoded again.

Below is an example of creating a custom TLS certificate and private key. This certificate will be site-specific and PEM encoded and we will Base-64 encoded the certificate and private key. Replace the Subject Name Internal Corporate CA and Common Name subdomain.corporation.com with values for your organization and HTTP/S domain name.

# create the root private key and CA

[user@host ] openssl genrsa -out ca.key 2048
[user@host ] openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.crt -subj "/CN=Internal Corporate CA"


# now create the server key and CSR
[user@host ] openssl genrsa -out server.key 2048
[user@host ] openssl req -new -key server.key -out server-csr.csr

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:
Organization Name (eg, company) [Default Company Ltd]:Corporation Name
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:subdomain.corporation.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:


# use CSR and server key to create the new server certificate
[user@host ] openssl x509 -req -in server-csr.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256

Signature ok
subject=C = US, L = Default City, O = Corporation Name, CN = subdomain.corporation.com
Getting CA Private Key


# pem encode the server cert
[user@host ] openssl x509 -outform pem -in server.crt -out server.pem

After performing these steps you will have the following files that will be used as the source of the inputs for creating a request to the create/update HTTP/S site endpoint: * server.key * server.pem

Both of these files are PEM encoded, which implies the contents are Base-64 encoded but they are formatted to include headers, footers and line-wrap. Before submitting the certificate and private key are inputs, apply another Base64 encoding on them.

Below are examples of performing this additional encoding state. The base64 command is given the -w 0 flag so that there is no wrapping of columns:

[user@host ] cat server.key | base64 -w 0 > server.key.b64

[user@host ] cat server.pem | base64 -w 0 > server.pem.b64

Now the string values of server.key.b64 and server.pem.b64 can be used with the request properties privateKey and ca respectively.

Remove HTTP Site

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

The HTTP site rule will removed and future traffic to the specified domain will not be routed to the tunnel.

This changes are sent to the client and will be negotiated between the it and the Spokes server. The server will drop the traffic relays and respond its operational status to the client. Once this is received, the client will remove the traffic from its configuration and send a response with the status field set to true.

Any errors during this operation will be returned the caller and the status field will be set to false.

`POST/api/admin/v1.0/tunnel/traffic/http/remove/:ID`

The request requires a field called domains and is composed of a list of domain names and will be used to remote existing HTTP site traffic rules.

Parameters

domain

string

Domain for HTTP/S traffic requested, e.g. example.com

Request

Remove traffic relays for an HTTP site using with this domain:

{
  "domains": [
    "host-123.spokes.example.com"
  ]
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

HTTP site remove success:

{
  "status": true
}

Allocate TCP Port

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

A port allocation operation will request an inbound TCP port from the Spokes server and assign it to a tunnel. This assignment is persistent. The port is not returned unless the client releases the port, giving it back to the server or when the tunnel is shutdown (terminated).

This endpoint will request a port from the Spokes server. When the Spokes server returns with a port, the client will save the port number to its configuration file and send a response with the status field set to true.

Any errors during this operation will be returned the caller and the status field will be set to false.

`GET/api/admin/v1.0/tunnel/traffic/tcp/allocate/:ID`

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

Port allocation operation success:

{
  "status": true
}

Release TCP Port

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

Releasing a port will return an inbound port, previously assigned to a tunnel, back to the Spokes server. It can then be potentially given another tunnel from that point on.

This request requires the inbound port number. The release operation will be performed on the Spokes server. The client will be given the success of this operation and update its configuration. Any existing traffic relays requested earlier will be dropped.

On success this endpoint will return a response with the status field set to true, otherwise false will be set and an error message included as well.

`POST/api/admin/v1.0/tunnel/traffic/tcp/release/:ID`

Request

Parameters

port

integer

Inbound port for application traffic. This port would be used by clients to connect to the upstream TCP service.

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

A successful port release operation:

{
  "status": true
}

A failure in the operation since the port was not assigned to the tunnel:

{
  "status": false,
  "error": "port number specified was not allocated to the tunnel"
}

Create / Update TCP Forwarding

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

Port traffic forwarding rules can be created, updated, or reset using this endpoint. Port allocations will also be performed as well if an inbound port is not specified.

An effective reset or clearing of a rule can also be performed by providing an inbound port and no destination host and destination port. The port allocation will remain with the tunnel, but the client will request the Spokes server no longer relay traffic from the inbound port to it since there is no destination.

This request will be sent to the client, validated and then wil be negotiated between the client and the Spokes server. The client will request a port allocated if necessary. It will then request traffic relays for that port to the specified destination.

The client will send a response with the status field set to true when all steps are successful, otherwise status is set to false and an error message provided.

`POST/api/admin/v1.0/tunnel/traffic/tcp/update/:ID`

The request requires a field called ports and is composed of a list of objects that define the TCP forwarding rules. The object fields and properties are defined below.

Parameters

port	integer	Inbound port for application traffic. This port would be used by clients to connect to the upstream TCP service.
destination	string	Forward traffic to this host or IP address.
dstPort	integer	The port number for the destination TCP service.
firewall	array of Firewall objects	List of firewall rules that are applied to the incoming traffic to this HTTP site, traffic can be allowed or dropped.

Request

Using an allocated TCP port, request TCP traffic forwarding with this inbound port and a local SSH server:

{
  "ports": [{
    "port": 22123,
    "destination": 127.0.0.1,
    "dstPort": 22
  }]
}

Forwarding traffic from allocated TCP port to a local SSH server but allowing incoming traffic from only two specific hosts:

{
  "ports": [{
    "port": 22123,
    "destination": 127.0.0.1,
    "dstPort": 22,
    "firewall": [
      {
        "sequence": 1,
        "action": "allow",
        "network": "9.18.124.47/32"
      },
      {
        "sequence": 2,
        "action": "allow",
        "network": "128.64.1.34/32"
      }
    ]
  }]
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

Port traffic forwarding response successful:

{
  "status": true
}

Reset TCP Forwarding

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

A port traffic reset is performed by providing an inbound port. The port allocation will remain with the tunnel, but the client will request the Spokes server no longer relay traffic from the inbound port to it since there is no destination.

The client will be negotiate the traffic changes with the Spokes server and drop the traffic relays. Once this is received, the client will clear the previous destination host and port values from its configuration and send a response with the status field set to true.

Any errors during this operation will be returned the caller and the status field will be set to false.

`POST/api/admin/v1.0/tunnel/traffic/tcp/reset/:ID`

Parameters

ports

integers

List of inbound port numbers for application traffic. This port would be used by clients to connect to the upstream TCP service.

Request

Reset TCP traffic forrwarding for a given port:

{
  "ports": [ 22123 ]
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

Reset an existing TCP traffic forwarding rule and cleared destination values from client config:

{
  "status": true
}

Create / Update Port Mapping

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

Port mapping is an rule on a client that maps a local listening port, e.g. 127.0.0.1:8080, to a service available behind a remote tunnel, e.g. remote-tun-123.domain.com. This enables tunnel-over-tunnel communication between hosts and services without having to expose or host the services on the public Internet.

Portmaps to external services can be created as well. An example could be SQL database hosted on a cloud provider like AWS Aurora. You can map it to appear like a locally running database server.

Port mapping rules require the parameters to help address the remote service and includes a destination which can be a hostname or IP address and a destination port. When the destination port is in the range of ports used to allocate TCP forwarding

The listening port is considered a "key" for portmaps. When creating a new portmap rule it must be specified. If the listen port is found in an existing rule, the new destination criteria will overwrite the rule that exists.

The response from the client includes a field called status that is a boolean value. A true value returned will indicate the port has mapped on the host, false otherwise.

`POST/api/admin/v1.0/tunnel/traffic/portmap/update/:ID`

The request requires a field called portmaps and is composed of a list of objects that define the port mapping rules. The object fields and properties are defined below.

Parameters

label	string	Brief description of the service behind mapped, for humans.
listenPort	integer	Local listening port that the remote service will be bound to.
transport	string	Transport protocol, "tcp" is the only available value.
destination	string	Hostname and IP address of the destination service. Mappings to services in the Spokes port range do not require a destination and can be left empty.
dstPort	integer	Destination port. For services available through an allocate TCP port, it should be that port. For HTTP/S services, it would be ports 80 or 443.
http	boolean	A boolean flag that indicates the traffic is HTTP-based. This allows other semantics and actions to be introduced in the future.

Request

Map a local port to a remote HTTP service hosted behind a tunnel:

{
  "portmaps": [{
    "listenPort": 8080,
    "transport": tcp,
    "destination": "remote-tun-123.domain.com",
    "dstPort": 80,
    "http": true
  }]
}

Map a local port to a cloud hosted database server. Note, this host will need to be included in the allow-list in the Spokes server configuration:

{
  "portmaps": [{
    "listenPort": 3306,
    "transport": tcp,
    "destination": "mycluster.cluster-123456789012.us-east-1.rds.amazonaws.com",
    "dstPort": 3306,
    "http": false
  }]
}

Map a port to an SSH server running on a remote host with a tunnel. A TCP port is allocated 22123 and forwarding traffic from that port 22 on this remote host:

{
  "portmaps": [{
    "listenPort": 2201,
    "transport": tcp,
    "destination": "",
    "dstPort": 22123,
    "http": false
  }]
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

Port mapping has been successfully established on the client:

{
  "status": true
}

Remove Port Mapping

This endpoint requires an ID to identify the tunnel. The tunnel will need to be online, if its not this endpoint will return a failure, e.g status set to false.

A portmap rule can be removed from the client by specifying the listening port. This value is a "key" for portmap rules and cannot be used in multiple rules on a client. The client will close the listening port and remove the rule from the configuration.

Any errors during this operation will be returned the caller and the status field will be set to false, on success the value will be set to true.

`POST/api/admin/v1.0/tunnel/traffic/portmap/remove/:ID`

Parameters

listenPort

integer

Local listening port that the remote service will be bound to.

Request

Remove Port Mapping rule for a given listening port on the host:

{
  "listenPort": 22123
}

Response

Parameters

status	boolean	Indicates if the request was completed successfully without any internal system errors
error	string	Internal system error message.
message	string	When when there is an error and a more contextual description of the issue can be provided.

Example Responses

Port mapping removed on the client-side and its configuration:

{
  "status": true
}

Ports

A range of ports is configured on the host and Spokes server and is used as a pool of ports that can be listened to and then forwarded to tunnels.

Ports allocations are requested by tunnels through their configuration and when they connect and establish new sessions. The endpoints described below can be used to list all of the ports that have been allocated across all of the tunnels and retrieve port configuration information.

Range

Fetch the port range that has configured on the server. Note, port allocations requested by clients are served by by randomly chosen from the set of ports available.

`GET/api/admin/v1.0/port/range`

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
range	Includes the range, start and end, for ports that can be allocated.

Example Response

Response:
{
  "status": true,
  "error": "",
  "range": {
    "begin": 22000,
    "end": 22999
  }
}

List

List all ports that have been allocated and the tunnels associated to them. The tunnel ID included in the output can be used to retrieve more information about the tunnel using the /api/v1.0/admin/tunnel endpoints.

`GET/api/admin/v1.0/port/list`

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
ports	List of port allocations and their associated tunnels (IDs)

Example Response

{
  "status": true,
  "error": "",
  "ports": [
    {
      "port": 22407,
      "tunID": "302a12f268074b6990820e7db09c3a04"
    },
    {
      "port": 22618,
      "tunID": "de5e60fa29fc44adb40f38f3fbd92bf9"
    }
  ]
}

User

This section describes the functionality for managing users on the Spokes server. Spokes has it's own set of administrative users that are used for loging in. However, it's possible that your instance of Spokes is being used to setup and manage tunnels for users (people) that exist in the broader software eco-system that Spokes is being integrated with.

Users can be imported to a Spokes server. From there a tunnel can be instantiated with attributes being set by the caller. Tunnels can be given restrictions that limit the domains that a user (client) can request traffic for.

Tunnels for users can be managed as well. For instance a tunnel session can be terminated, knocking the user temporarily offline.

Users can also be set in a state such that incoming tunnel connections will be dropped. This can be used if use needs to paused without necessarily deleting the user from the system.

Other tunnel operations such as getting detailed information, remote client configuration information and shutting tunnels downs can be performed using the /api/v1.0/admin/tunnel endpoints.

List

List all of the users that were imported or created on the system. These are basic users. Users that have deactivated will be include in this list. Administrative users created on the CLI will not be included in this list.

`GET/api/admin/v1.0/user/list`

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
users	A list of (basic) users. This endpoint will not return admins.

Example Response

Response:
{
  "status": true,
  "error": "",
  "users": [
    ...
  ]
}

Create

Add a user to the system. It includes other parameters such as email, fullname and phone number but these are all optional.

A user object is returned on success. The ID from the user can be used for tracking or management outside of the Spokes server.

`POST/api/admin/v1.0/user/create`

Parameters

email	`optional` Email address for user, it should be unique if it's a valid, non-zero length value.
fullname	`optional` Fullname for the user.
phone	`optional` A contact number for the user.

Request

{
  "email": "user@example.com",
  "fullname": "Jane Doe",
  "phone": "+1-888-876-5309"
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
user	The user object created through this operation is returned.

Example Response

{
  "status": true,
  "error": "",
  "user": {
    ...
  }
}

Edit

Edit an existing user and change attributes for the user. This endpoint will use all the fields in the request, including empty values.

Be sure to include original values if you intend to only change one attribute. Otherwise empty values will be used to make changes to the backend.

`POST/api/admin/v1.0/user/edit`

Parameters

ID	A unique ID using the UUIDv4 format and the hyphens removed.
email	`optional` Email address for user, it should be unique if it's a valid, non-zero length value.
fullname	`optional` Fullname for the user.
phone	`optional` A contact number for the user.
active	`optional` Boolean flag that is used to activate or deactivate a user

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca",
  "email": "user@example.com",
  "fullname": "Jane Doe",
  "phone": "+1-888-876-5309",
  "active": true
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

{
  "status": true,
  "error": ""
}

Import

Creates a user on the system but allows the caller to specify the 16-byte UUIDv4 ID (remove the hyphens).

This API assumes a user exists in an external system and is being imported to Spokes. It provides more control the ID to calle and should enable external applications to build their own management system around users.

`POST/api/admin/v1.0/user/import`

Parameters

ID	A unique ID using the UUIDv4 format and the hyphens removed.
email	`optional` Email address for user, it should be unique if it's a valid, non-zero length value.
fullname	`optional` Fullname for the user.
phone	`optional` A contact number for the user.

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca",
  "email": "user@example.com",
  "fullname": "Jane Doe",
  "phone": "+1-888-876-5309"
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
user	The user object created through this operation is returned.

Example Response

{
  "status": true,
  "error": "",
  "user": {
    ...
  }
}

Activate

This endpoint is used to activate or deactivate a user. A deactivated user is not deleted, however, any future tunnel sessions cannot be established.

The user will be given an error message to let them know their account has been disabled when their tunnel(s) attempt to authenticate.

This function can be coupled with stopping tunnels if you're looking at stopping currently running tunnels and preventing them from reconnecting immediately afterwards.

`POST/api/admin/v1.0/user/activate`

Parameters

userID	Unique ID that identifies the user
active	Boolean flag that is used to activate or deactivate a user

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca",
  "active": false
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": ""
}

Create Tunnel

Create a tunnel associated to the user. This operation will create a tunnel instance in the backedn and a corresponding authentication token.

The authentication token will be returned along with the tunnel object.

The caller can specify a name for the tunnel. This is a humanly readable name. A hostname can be specified as well. The hostname can be functional if the Spokes server admin created DNS records (wildcard) that would support proper resolution to the Spokes server.

`POST/api/admin/v1.0/user/tunnel/create`

Parameters

userID	Unique ID that identifies the user
name	A name for the tunnel, intended for humans.
hostname	Hostname for the tunnel.

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca",
  "name": "hello-world tunnel",
  "hostname": "hello-world.packetdemo.com"
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
tunnel	Tunnel object created through a successful operation
token	Corresponding authentication token. The token value can be propogated to client to auth with the Spokes server.

Example Response

Response:
{
  "status": true,
  "error": "",
  "tunnel": {
    ...
  },
  "token": {
    ...
  }
}

Stop Tunnel

Stop a specific tunnel for the user. The tunnel session will be terminated and closed on the server-side.

Note, the default behavior for the Packetriot client is to re-connect. If you're interested in preventing the client from re-connecting, temporarily deactivate user and then stop the tunnel.

`GET/api/admin/v1.0/user/tunnel/stop/:ID`

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": ""
}

List Tunnels

List all of the active tunnels for the user using their unique ID. The tunnel objects returned are shallow objects and do not include any additional information such as the HTTP or Port traffic relays that were last active.

More information can be gathered using /api/v1.0/admin/tunnel endpoints.

`GET/api/admin/v1.0/user/tunnel/list/:ID`

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": "",
  "tunnels": [
    ...
  ]
}

Set Bandwidth Cap

Users can be capped for the bandwidth they consume over a monthly period. With this endpoint the max amount of data (MB) can be set.

When a user has met their cap their tunnels will be stopped. Future authentication attempts will fail with an error message provided to the use that it's bandwidth related.

Callers can also remove the bandwidth cap by setting this value to zero.

Monthly bandwidth statistics are reset on the first of each month at 00:00:00 UTC.

`POST/api/admin/v1.0/user/bandwidth/cap`

Parameters

userID	Unique ID that identifies the user
max	Maximum amount of traffic (MB) a user can consume monthly

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca",
  "max": "1000"
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": ""
}

Domains

The section below describe several endpoints for managing domains associated to the user. These domains are used to restrict HTTP/S traffic that can be requested by the client.

When no set of domains are allowed to the user, then all domains will be accepted by the Spokes server. This mechanism can be used to enforce and restrict tunnels and used a security mechanism.

Allow

Restrictions can be placed on users regarding the domains requested for HTTP/S traffic.

This endpoint allows caller to add domains or subdomains that are allowed to be requested by the the client. Traffic to valid subdomains will be accepted by the Spokes server.

A caller can allow the domain testing.packetdemo.com and traffic requested for that domains and subdomain.testing.packetdemo.com will be permitted by the Spokes server.

Once a domain is allowed the Spokes server will reject requests for any HTTP/S that is not in the set of allowed domains.

Domains that already exist will be skipped.

`POST/api/admin/v1.0/user/domain/allow`

Parameters

userID	Unique ID that identifies the user
domains	A list of domains or subdomains to add to the list of domains allowed for use

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca",
  "domains": [
    "example.com",
    "packetdemo.com"
  ]
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": ""
}

Remove

This endpoint allows callers to remove domains from the set of domains previously allowed for a user. No errors are returned if the domains are not found in the specified users allow-list.

`POST/api/admin/v1.0/user/domain/remove`

Parameters

userID	Unique ID that identifies the user
domains	List of domains and subdomains to remove

Request

{
  "userID": "34a7fb347ef9dc7238788eaa3e1bd954ca3dd7ffc0dfd42901de90f9a52ed663",
  "domains": [
    "example.com",
    "packetdemo.com"
  ]
}

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": ""
}

List Restrictions

This endpoint will return the list of domains that are associated to a user. These domains can be requested in HTTP/S traffic rules by tunnels associated the user.

Traffic rules request domains not in this list will be rejected by the Spokes server.

`GET/api/admin/v1.0/user/domain/list/:ID`

Parameters

ID	Unique ID that identifies the user

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`
domains	A list of domains or subdomains associated to the list of domains allowed for the specified user.

Example Response

Response:
{
  "status": true,
  "error": "",
  "domains": [
    "example.com",
    "packetdemo.com"
  ]
}

Reset Restrictions

This endpoint will remove all domain restrictions that are applied to a users tunnels when HTTP/S traffic requests are made.

`GET/api/admin/v1.0/user/domain/reset/:ID`

Parameters

ID	Unique ID that identifies the user

Response

Parameters

status	Indicates if the request was completed successfully without any internal system errors
error	Error message set by server when status is set to `false`

Example Response

Response:
{
  "status": true,
  "error": ""
}

Data Types

In this section we define in more detail the data types are returned in some of the responses in the API. In each section we describe the meaning of value, different use-cases and the valid ranges.

Token

This section describes the properties in the token message. These are registration tokens that are used by the Packetriot client to configure new tunnels. A registration enables the client to request the creation of an authentication token for itself.

This message structure is also representative to other tokens used in the system such as authentication and API tokens. Authentication tokens are not exposed via this API. API tokens are used for authentication and utilizing the API described in this document.

The value of the token is used by external applications for identification and authentication.

id	Unique ID for the token.
created	Unique ID for the token.
modified	Unique ID for the token.
active	Unique ID for the token.
description	Unique ID for the token.
value	This is the token value that is used for authentication.

Tunnel

The tunnel object and it's attributes are described below. These values are maintained dynamically and some periodically. For example, the bandwidth statistics are captured with a slighlt delay, but those HTTP and Port traffic statistics are rolled up to the tunnel every 5 minutes.

id	Unique ID for the tunnel, this ID can be used with operations like getting detailed information on the tunnel, its client configuration and shutting it down.
userID	ID of the user that the tunnel is associated to. This user ID can be related to an actual user if the tunnel was created using the `/api/v1.0/user` APIs. When a tunnel is created using a registration token it's just a necesary artifact thats needed for tunnels.
created	Time the tunnel was created.
lastActive	Last time this tunnel was active, this timestamp is updated perdiocally during the tunnel session.
state	State of the tunnel: init (1), online (2), offline (3), shutdown (4) and deleted (5)
uptime	Number of seconds the tunnel as online for.
bandwidth	The daily and monthly bandwidth across all services hosted in the tunnel. As connections are established and then closed the stats are recorded. Monthly stats are reset on the first of each month at 00:00:00.
name	The name of the tunnel is not set.
hostname	Hostname assignment for a tunnel. This value can be functional if the Spokes server and domains names (wildcards) are setup to make them functional. Otherwise this value can be used as a label or nickname.
version	Version of the client.
os	Operating system the client is running on.
arch	Computer architecture: x86-64, x86-32, arm32, arm64.
https	List of last active HTTP/S traffic relays
ports	List of last active Port traffic relays for TCP

Tunnel-Link

The tunnel link object describes the details in a page created to store results from a tunnel listing operation: active, online, search or listing all tunnels. These results are paged when larger than 50 objects.

uid	Unique ID for the paged object, this ID is used with the `/api/admin/v1.0/tunnel/page/:uid` endpoint to retrieve the tunnel objects stored in this page.
order	A sequential number for the page: 1-n.
count	Number of tunnels objects stored in the page.
url	A URL provided for convenience that will access `GET` the endpoint `/api/admin/v1.0/tunnel/page/:uid` to return the tunnel objects.

Http

The object below describes the HTTP traffic that was requested by a Packetriot client and stored. It includes runtime data such as bandwidth.

id	ID of the HTTP/S traffic relay
userID	Associated user ID, this value will match the user ID associated the tunnel.
tunID	Unique ID of the associated tunnel.
active	True or false, indicates that this relay was requested during a tunnel most recent session. Note, when a client HTTP/S traffic relay rules are edited and some removed, the record will be in the backend database but no longer active.
available	True or false, indicates that the destination of the traffic, e.g. upstream server is available.
secure	True or false, indicates the HTTP relay is requested HTTPS (tcp:443) traffic as well.
domainName	Domain name for the HTTP traffic, e.g. example.com, subdomain.exmaple.com
bandwidth	The daily and monthly bandwidth is maintained as new connections are established and then closed. Monthly stats are reset on the first of each month at 00:00:00.

Port

The object below describes the port traffic that was requested by a Packetriot client and stored. It includes runtime data such as bandwidth.

id	ID of the HTTP/S traffic relay
userID	Associated user ID, this value will match the user ID associated the tunnel.
tunID	Unique ID of the associated tunnel.
active	True or false, indicates that this relay was requested during a tunnel most recent session. Note, when a client port traffic relay rules are edited and some removed, the record will be in the backend database but no longer active.
available	True or false, indicates that the destination of the traffic, e.g. upstream server is available.
protocol	TCP (1) or UDP (2). Note, UDP tunneling is not yet supported.
port	The port allocated to the tunnel. This port is from the range of ports configured for the Spokes server.
bandwidth	The daily and monthly bandwidth is maintained as new connections are established and then closed. Monthly stats are reset on the first of each month at 00:00:00.
label

Client Configuration

The message definition below is the parent object for tunnel configurations. It includes two attributes that are defined further: https and ports. These two attributes store the HTTP and TCP traffic rules.

version	Version of the Packetriot client.
os	Operating system the client is running on.
arch	Architecture: x86-64, x86-32, arm32, arm64, ...
https	List of HTTP/S traffic rules.
ports	List of TCP traffic rules.

Http

The HTTP traffic rule object is described below. This object is used for storing the details for a rule that was created and store by the Packetriot client. This message is also used by the Spokes server for sending updates or new rules to the client remotely.

Not all of the attributes in this message are populated. Some attributes such useLetsEncrypt, webRoot, redirect, redirectURL, etc... are only used when there are values given or when the values are set to true.

Typically the CLI or Spokes web administrative dashboard is used for properly setting these values.

domain	Domain for HTTP/S traffic requested, e.g. example.com
secure	True indicates https (443) traffic is also requested.
destination	Forward to this host/address.
port	Port on destination to forward HTTP (plain-text) traffic to. Note, TLS is terminated in the Packetriot client when using Let's Encrypt or custom certificates, so incoming client traffic can be HTTPS.
tls	Port to forward TLS traffic, transparent TLS proxying.
webRoot	Path on local file-system (for client) to serve static content or assets.
useLetsEnc	Boolean flag to indicate lets-encrypt for TLS certificates.
ca	Path to custom certificate authority, this is the copy made by the Packetriot client.
privateKey	Path to custom privacy key, this is the copy made by the Packetriot client.
redirect	Boolean that indicates whether HTTP is redirected to HTTPS.
password	Salted-hash of password to permit traffic.
basicHttpAuth	Salted-hash of user:password (HTTP basic auth) to permit traffic.
redirectURL	URL that all incoming requests are redirected to.
rewriteHost	Rewrite the `Host` header with this value.

Port

The port object is described below.

port	Incoming port allocated to client that is hosted by the Spokes server, e.g. 22001.
destination	The host or IP address to forward the traffic to.
dstPort	Destination port on the host to forward traffic to.

Firewall Rule

The firewall rule object is described below. It's utilized as a list of objects in an individual HTTP and Port traffic rules. The property name for both traffic rule definitions is firewall.

A firewall rule instructs the server to accept or drop traffic using specified host or network. Hosts and networks are identified using CIDR notation. IPv4 and IPv6 addresses are supported.

When traffic is examined against a set of rules, the drop rules are applied first. The allow rules are applied aftewards.

Normally only one set of actions, allow or drop, are used when defining firewall rules for traffic. Once an allow rule is processed, all other traffic not specified with an allow is dropped, which makes including a drop rule meaningless.

sequence	integer	`optional` The sequence number of the rule orders the application of the firewall rules when processed by the server. The server will set an incrementing sequence number starting from `MAX SEQ` when this value is left out.
action	string	Allowed values are: allow, drop. Allow will instruct server to accept incoming connections from the network specified in this fireall rule.
network	string	Source network identified using CIDR, e.g. 1.2.3.4/16 or 2345:0425:2CA1:0000::0000/64 for IPv6.

User

The following object is used to describe the user. High-level details are returned to the user. Only basic users, those created with the /api/v1.0/admin/user endpoints are returned using this object.

The email, fullname and phone attributes are empty and completely optional.

id	Unique ID for user.
created	Timestamp for when the user was created or imported.
email	Email address for the user.
fullname	Fullname for the user.
phone	Phone/mobile number for the user.
maxBandwidth	The maximum monthly bandwidth (MB) allocated for the month.