Getting started with the cThings Cloud API

The cThings Cloud API provides programmatic access to functionality and data available via cThings Cloud. The cThings Cloud API is a REST API that exchanges JSON data and is protected by OAuth2. This article outlines how to request an access token from the cThings AuthServer; how to use this token to make a request to the cThings Cloud API; and provides a list of available endpoints.

Security

Your credentials

To request an access token from the cThings AuthServer you will need a username (formaly a Client ID) and a password (formaly a Client Secret).

You should be provided with your credentials by cThings. Please get in touch with cThings Support of you do not have credentials.

The Client ID is a UUID, e.g. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, and Client Secret an arbitrary alphanumeric string, e.g. xxxxxxxxxxxxxxxxxxxxxxxx.

Obtaining an Access Token

An access token can be requested from the cThings AuthServer using your credentials. The cThings AuthServer implements the OAuth2 specification, specifically the Client Credentials grant type. To request an access token, make a POST request to the following endpoint.

https://authserver.cthings.cloud/token

Include the following parameters as multipart/form-data (set the Content-Type header to multipart/form-data).

Request Parameters	Value
grant_type	client_credentials
scope	api

Include your Client ID and Ciient Secret as a Basic Auth username and password. This is done by generating a Base64 encoded string of your Client ID and Client Secret, separated by a colon. For example, a Client ID and Client Secret with all x's would result in the following concatenation.

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxxxx

This would result in the following Base64 encoded string being generated.

eHh4eHh4eHgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4Onh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eA==

The above Base64 encoded string should be prepended with Basic and included as an Authoization header. The following headers should therefore be included alongside your request to the cThings AuthServer.

Header Parameters	Value
Content-Type	multipart/form-data
Authorization	Basic eHh4eHh4eHgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4Onh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eA==

If successful, the following response will be returned.

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4eHh4eHh4eC14eHh4LXh4eHgteHh4eC14eHh4eHh4eHh4eHgiLCJpc3MiOiJhdXRoc2VydmVyLmN0aGluZ3MuY2xvdWQiLCJhdWQiOiJ4eHh4eHh4eC14eHh4LXh4eHgteHh4eC14eHh4eHh4eHh4eHgiLCJpYXQiOjE2ODY2NDYyNjYsImV4cCI6MTY4NjY0OTg2Niwic2NvcGUiOltdfQ.Ftcay_HdiQ2rlfxVu42N-w19bpNTRfbeppc60R0PzrU",
    "expires_in": 3600,
    "scope": ["api"],
    "token_type": "Bearer"
}

The above can also be achieved using the native authorisation tools offered by API clients such as Postman and Insomnia. Below is an example configuration to request an access token using Postman Authorization.

API Requests

Making a simple API request

Using the access token requested from the cThings AuthServer a secure API request can be made to the cThings Cloud API. The following outlines making a simple GET request to retrieve data from a single device. To make this request, a Device ID is required, a Device ID is a UUID and can be obtained from the API or the URL in cThings Cloud. For example, when on a device in cThings Cloud the following URL, https://cthings.cloud/device/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, gives the ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

A GET request can be made to the following URL.

https://api.cthings.cloud/v3/device/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The access token must be passed as an Authorization header and prefixed with Bearer. The following table outlines an example Authorization header.

Header Parameters	Value
Authorization	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4eHh4eHh4eC14eHh4LXh4eHgteHh...

If successful, the following response will be returned.

{
    "api": "cThings Cloud API",
    "code": 200,
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "device": "xxxxxxxxxxxxxxxx",
        "name": "Example Device",
        "settings": {},
        "type": {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "key": "example_type_key",
            "type": "Example Type"
        },
        "active": true,
        "connection": {
            "status": true,
            "lastConnected": "2020-01-01T12:00:00Z",
            "signalStrength": -48.0000,
            "route": [
                "xxxxxxxxxxxxxxxx",
                "xxxxxxxxxxxxxxxx"
            ]
        },
        "ingest": {
            "identifier": "xxxxxxxxxxxxxxxx",
            "template": null,
            "timeShift": {
                "timeShift": 0,
                "inherited": true
            }
        },
        "provider": {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "provider": "cThings"
        },
        "manufacturer": {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "manufacturer": "Example Manufacturer"
        },
        "entity": {
            "name": "Example Entity",
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        },
        "node": {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "Example Device",
            "serial": "AAAABBBBCCCCDDDD"
        },
        "watchlist": true,
        "servicePoint": {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "type": "Example Device Type"
        },
        "timeBinKey": 4,
        "dataInterval": 60,
        "liveAt": "2020-01-01T12:00:00Z",
        "isTest": true,
        "location": {
            "latitude": 52.123456,
            "longitude": 0.123456
        },
        "configuration": {
            "test": true
        },
        "downlinkProtocol": [],
        "tasks": [],
        "createdAt": "2020-01-01T12:00:00Z"
    },
    "links": {},
    "message": null,
    "request": {
        "url": "http://api.cthings.cloud/v3/device/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "method": "GET",
        "body": {}
    },
    "websocket": false,
    "version": "3.13.1"
}

API documentation and versioning

A complete list of endpoints and how to use them can be found here.

https://api.cthings.cloud/docs/v2
https://api.cthings.cloud/docs/v3

There are two versions of the cThings Cloud API, v2 and v3. Wherever possible v3 should be used as it provides a better all around experience. Some endpoints aren't available in the v3 version, in which case you should fallback to v2.

Example request (Python)

Below is an example of how to make the access token request using Python, using the requests library.

import requests
import base64

# first we request a token from the cThings AuthServer

url = "https://authserver.cthings.cloud/token"
username = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
password = "xxxxxxxxxxxxxxxxxxxxxxxx"

# generate a base64 encoded string of the username and password

base64EncodedCredentials = base64.b64encode((username + ":" + password).encode("utf-8")).decode("utf-8")

# define the request parameters and headers

params = {
    "grant_type": "client_credentials",
    "scope": "api"
}

headers = {
    "Authorization": "Basic " + base64EncodedCredentials
}

# send the POST request

response = requests.post(url, data=params, headers=headers)
print (response.json())

# check if the request was successful (status code 200)

if response.status_code == 200:
    access_token = response.json()["access_token"]
    print("Access token:", access_token)
else:
    print("Request failed with status code:", response.status_code)

# make request to the cThings API

url = "https://api.cthings.cloud/v3/device/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

headers = {
    "Authorization": "Bearer " + access_token
}

response = requests.get(url, headers=headers)

# check if the request was successful (status code 200)

if response.status_code == 200:
    data = response.json()
    print("data:", data)
else:
    print("Request failed with status code:", response.status_code)

Updated on: 20/10/2023