This is preliminary documentation. It applies only to networks running under CloudTrax 4.
*Note that there are no access charges associated with use of the CloudTrax API for users with fewer than 100 devices. For pricing on more than 100 devices, contact [email protected]. *
- Overview
- Introduction
- Required headers
- Errors
- Authentication
- An API Server test harness
- Endpoint Details
This document describes the CloudTrax API, an Application Programming Interface that allows you to create, access, configure, and manipulate your CloudTrax networks and their Access Points. The API provides the facilities to let you recreate, if desired, the functionality of the CloudTrax Dashboard and have it entirely under your own control.
The API is comprised of the following endpoint collections:
| endpoints | description |
|---|---|
| Account Management | Create new user accounts, log in users with username and password, provide embedded web access to CloudTrax visuals, and manage service agreements |
| User Management | Manage users with the new CloudTrax user system |
| Client Management | Block and edit clients |
| History | View traffic statistics in a given domain over a time span |
| Network Group Management | Create, list and delete network groups |
| Network Management | Create, list, and delete networks |
| Node Management | Create, list, update, delete, and test for characteristics of Access Points (also called nodes) |
| Switch Management | Create, list, update, delete, and test for characteristics of Switches |
| Powerstrip Management | Create, list, update, delete, and test for characteristics of Powerstrips |
| Site Survey | Scan Access Points in a network for neighboring Access Points |
| Time | Synchronize time against the API server |
| Vouchers | Create, list, and update vouchers allowing per-user access to your networks |
In order to use the facilities of the API, you'll need to have the API keys relevant to your account and/or network(s). See Retrieving API Keys for more information about this.
The CloudTrax API is RESTful. It uses the HTTP methods (or verbs), GET, POST, PUT, and DELETE, to retrieve, create, update, and delete, respectively, CloudTrax-based resources. The resources themselves, as well as the operations performed on them, are specified in RESTful fashion by the path component of the URL that addresses the CloudTrax API server.
Because the API is RESTful, it's the combination of HTTP method plus path that fully specifies, or describes, an API endpoint or call. For example, the endpoint that's described in this documentation as:
PUT /node/<node-id>
will actually be invoked as:
https://api.cloudtrax.com/node/<node-id>
with your HTTP client indicating separately that this call is a PUT.
Note: the word node as used in the API and at places in this documentation is a nickname for Access Point. The two are equivalent.
The effect of this endpoint is to update the node with id node-id with the information contained in the JSON structure that's passed in as the HTTP message body. The same path used in conjunction with the HTTP method DELETE:
DELETE /node/<node-id>
has the effect of deleting that node.
Here's another example in a bit more detail. The API call requesting a list of all CloudTrax networks belonging to a particular user is specified by the endpoint GET /network/list. We could invoke this call using the curl HTTP client on the command line, requesting verbose output as follows:
curl -v https://api.cloudtrax.com/network/list
This would produce the following output, showing the GET followed by the three Request Headers produced by the curl client in this case:
> GET /network/list HTTP/1.1
> User-Agent: curl/7.37.1
> Host: api.cloudtrax.com
> Accept: */*
...
If this call were successful, the body of the HTTP Response would return a JSON structure showing information on each network found. This particular call will fail however because all CloudTrax API calls need to be authenticated before they can be run (see Authentication below), and we haven't done that here. What curl will show in this instance is a piece of JSON reporting the particular type of authentication error that occurred:
{
"errors": [
{
"code": 13001,
"message": "No nonce or timestamp in header.",
"context": "authorize",
"values": {
}
}
]
}
Since this particular call uses GET, you could in the spirit of experimentation also invoke it directly from the address bar of your favorite web browser to see what happens:
https://api.cloudtrax.com/network/list
This will return the same error-reporting JSON as above (though not as nicely prettified, since the HTML will blithely ignore all internal linefeeds and reduce whitespace to a minimum).
If the above call had been properly authenticated and was successful, the returned JSON might have looked something like this:
{
"networks": [
{
"name": "hk_test_network",
"id": 135587,
"latitude": 49.44026050000000083,
"longitude": -123.6724020000000053,
"down_repeater": 1,
"down_gateway": 0,
"spare_nodes": 0,
"node_count": 2
}
]
}
Several of the GET-based calls in this API use an HTTP query-string to pass additional information to the server. For example, the GET /history/network/<net-id> call can add an optional "time span" parameter as in the following:
GET https://api.cloudtrax.com/history/network/12478?period=week
As already mentioned, POST and PUT requests that create new resources or update existing resources, respectively, pass required information in the body of the HTTP Request as a JSON structure. The POST /network request to create a new network, for example, will need to add a JSON body something like the following:
{
"name":"newNetworkTest_2",
"password":"passwordForNetwork",
"email":"[email protected]",
"location":"Moose Jaw",
"timezone":"Canada/Central",
"country_code":"CA"
}
The API expects all HTTP Requests to contain the following headers:
| header-name | header-value | notes |
|---|---|---|
Host: |
api.cloudtrax.com | Most HTTP libraries/clients generate this header automatically for the given URL. All CloudTrax API calls use this hostname. |
Content-Length: |
length in bytes of the Request body | Generated automatically by most libraries/clients. Length will be 0 for body-less requests. |
Content-Type: |
'application/json' | PUT and POST requests will be passing JSON structures to the server. |
OpenMesh-API-Version: |
1 | Version of the API to use. 0 assumed if this header is missing. Incorrect versioning may cause difficult-to-diagnose errors. |
Authorization: |
see Authentication | Required on all requests. |
Signature: |
see Authentication | Required on all requests. |
For a list of the actual errors that can occur during API operations, see the Error codes document.
Errors are returned in a consistent fashion throughout the API. A non-200 HTTP status code (e.g. 404 HTTP_NOT_FOUND or 403 HTTP_FORBIDDEN) provides a hint as to the general nature of the error, and the body of the returned JSON provides more detailed information. For instance, If you try to create a network with a name that already exists and use an invalid country code as well, you'll get an HTTP_FORBIDDEN error with the following body:
{
"errors": [
{
"code": 12001,
"context": "name",
"message": "String length (104) out of range (1 - 100).",
"values": {
"length": "104",
"max": "100",
"min": "1"
}
},
{
"code": 12005,
"context": "country_code",
"message": "Unknown country code.",
"values": {}
}
]
}
"errors" is an array of one or more specific error elements. Each element has the following fields:
| field | description |
|---|---|
| code | a unique error code |
| context | further information about where the error occurred |
| message | an English-language error string suitable for display |
| values | a list of key-value pairs that were the specific values used to create the error message. Not all error messages have values. |
Code 1009 is a special non-error status-type code that is used to indicate "Success" on the completion of certain operations that do not themselves otherwise return JSON output. A successful update node call, for example, returns a JSON 1009 "Success" element to indicate a successful update:
{
"code": 1009,
"message": "Success.",
"context": "update_node",
"values": {
}
}The exceptions are calls in the Cloud AP's endpoint collection. For technical reasons, none of these endpoints return JSON, and their HTTP Response status codes need to be checked directly for either 200 Success or 40x Failure.
See the Error codes document.
As noted above, all CloudTrax API calls need to be authenticated. Authentication is the process of determining that the user making this call is known and acceptable to the system. This requires adding two additional headers to every HTTP Request: 'Authorization:' and 'Signature:'. We'll first take a brief look at keys.
Keys are an essential part of the authentication process, since they identify users and the degree of access they're allowed to the CloudTrax system. The term key is used here loosely: access to the API is actually controlled by a key pair consisting of a key and a secret, both of which are required for API access. Keys come in three types.
| type of key | provides access to |
|---|---|
account |
All networks belonging to an account, with the ability to create new networks |
network |
A single network |
application |
API endpoints that allow the creation of new accounts and log-in of users |
-
accountkeys (also called master-level keys) are the most common type of key. They provide access to all networks assigned to an account and allow their account holders to create new networks on an ad hoc basis. -
networkkeys allow their clients to use nearly all the same endpoints as an account-level key holder, but access is restricted to a single network. A typical use-case would be a hotel chain that maintains hotels in different cities. A differentnetworkkey would be assigned to each hotel in the chain, restricting access at each hotel to its own network. Administrators at head office would be able to use anaccountkey to oversee and manage all corporate networks system-wide. -
applicationkeys provide access to several endpoints that are not available to the other key types. These endpoints provide the functionality required to create new accounts and to retrieve account and network keys given username and password. An application, say a smartphone app, would use anapplicationkey to create new accounts and allows users to log in using their username and password. See the document Account Management endpoints for details.
Whichever type of key you have, the authentication process described below is identical.
As described above, you must have the relevant key and secret for your account and/or network(s) in order to use the API as described in this document. To generate the needed key and secret, see the CloudTrax Help Center article "Generating an API Key".
Note that currently there are no access charges associated with use of the CloudTrax API for users with fewer than 100 devices. For more than 100 devices, contact [email protected] for pricing. Open Mesh may enforce rate limiting for some uses of the API. In order to help constrain resource demands, we ask that you please attempt to design any systems utilizing the API to limit frequency of access to the API.
Generating the "Authorization:" header is straightforward. It is formed by the string concatenation of three key-value pairs:
- an appropriate key, depending on which API is being called
- a Unix timestamp
- a so-called "Number-Used-Once" nonce
An easy-to-fix error here, 13002, is occasioned by providing a timestamp that differs from the server's time by more than 15 minutes. Call the GET /time endpoint to retrieve the "correct" time (from the server's perspective), and adjust your own accordingly. Nonces, a cryptographic device used to ensure that older communications cannot be reused in replay attacks, also need to be unique across all API calls during a time window that varies between 15 to 30 minutes (13003). (This error is easily avoided by generating a random nonce on every call.)
As noted above, all CloudTrax API calls are required to be signed by either an application-level or an account- or network-level key. Which is used depends on the particular call being made.
Here's a piece of PHP showing the authentication operation:
$key = '1b88730ac5ba6000a1271e0b2a2edb5a163ce77bf9630850f22f8ca3de490a5f';
$nonce = 'ThisIsANonce';
$authorization = "key=" . $key . ",timestamp=" . time() . ",nonce=" . $nonce;
$authorization_header = "Authorization: " . $authorization;Note that there are no spaces in the concatenated authorization string (though there is one following the colon (":") in the Authorization header itself, as allowed by the HTTP protocol).
Generating the "Signature:" header is a teeny bit more complicated perhaps, but not by much. You need to create an HMAC SHA-256 hashed form of the authorization string concatenated with the endpoint's path, keyed on the secret string shared between you and the CloudTrax server. Certainly the code is straightforward; here it is in PHP:
$signature = hash_hmac('sha256', $authorization . $path, $secret);
$sig_header = "Signature: " . $signature;One final wrinkle is that the above HMAC keyed hash example only works as is with GET and DELETE. If you're working with either POST or PUT endpoints that pass a JSON structure in the message body, you'll need to concatenate that body onto the first, "message" argument of the hash_hmac function:
$signature = hash_hmac('sha256', $authorization . $path . $jsonbody, $secret);If you're getting back a 13000 "Signature wrong" error on your calls, check if you're attempting to create a signature on a PUT or POST without concatenating the HTTP message body as well.
Whatever form the signature takes, the authorization and signature headers need to be present for every API request you make.
An accompanying document, An API Server test harness, provides PHP working-code examples of how to call individual API's from several of the endpoint collections: Network Management , Node Management, and Network Settings. These calls cover the entire RESTful gamut of GET, POST, PUT, and DELETE and provide a representative sample of the types of endpoints in the API and how to call them.
For reference purposes, here is the full list of endpoint collections comprising the CloudTrax API. Dive into the following sections for details about specific API endpoints:
| endpoints | description |
|---|---|
| Account Management | Create new user accounts, log in users with username and password, provide embedded web access to CloudTrax visuals, and manage service agreements |
| Network Management | Create, list, and delete networks |
| Node Management | Create, list, update, delete, and test for characteristics of nodes |
| History | View traffic statistics in a given domain over a time span |
| Site Survey | Scan nodes in a network for neighboring Access Points |
| Time | Synchronize time against the API server |