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.
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.
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).
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.
If successful, the following response will be returned.
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.
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.
If successful, the following response will be returned.
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.
Below is an example of how to make the access token request using Python, using the requests library.
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
Thank you!