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 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 Information about the operation.
error 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 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 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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
maxTunnels Maximum number of tunnels that can be active at any given time.
expires 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 A description for the registration token
active 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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
tokens 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 Indicates if the request was completed successfully without any internal system errors
error 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 Unique ID for the registration token
description An update description
active Boolean flag that will set registration active (usable) or not

Request
{
  "tokenID": "d6c52563f18f47ae9714b3a5a972fe0e"
}
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

{
  "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 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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
tunnels List of active tunnels.

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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
tunnels List of tunnels that are currently online and connected to the Spokes server.

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"
    },
  ]
}

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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
tunnels List of all tunnels in the database.

Example Response

{
  "status": true,
  "error": "",
  "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 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 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 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": ""
}

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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
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, so 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 Indicates if the request was completed successfully without any internal system errors
error Error message set by server when status is set to false
config 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
      }
    ]
  }
}

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

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.

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.