The HTTP/HTTPS Connector
Written by Matthew Clark-Massera
Updated at March 21st, 2024
Table of Contents
Please see our article Choosing an Integration Strategy for a discussion on the various integration options with our devices.
This article outlines the function and features of the HTTP/HTTPS JSON connector and how they can be used in integrating our devices into a 3rd party platform. Contact our support team for integration documents containing the payloads that will be sent.
The authorization and authentication requirements of many systems can be accommodated.
Overview
When using OEM Server - devices send their data to OEM Server in their 'native' protocol, which is raw TCP. OEM Server handles device management including firmware updates, parameter updates, debugging, and controls where this data is then directed.
When using the TCP connector - the raw TCP is simply forwarded to the end server (front-end tracking platform)
When using the HTTP connector, the data is repackaged by OEM Server and the data is sent in JSON format via HTTP POST to the desired endpoint. The end server must respond 200 OK to confirm the message has been received, and then OEM Server instructs the device to delete these messages from its memory, since they have been saved to the server.
Connectors control this in OEM. Connectors can be set up as shown here - Create a Connector
Connector Options - Dynamic Fields
As part of the connector setup, we are able to configure up to 3 headers to be sent as part of the HTTP POST, and several dynamic fields can be included in the URL or headers.
Available dynamic fields:
- [SERIAL]
- [IMEI]
- [ICCID]
- [CUSTOM1]
- [CUSTOM2]
- [CUSTOM3]
Custom 1, 2 and 3 are fields which can be set by the user via API call. Contact support for details.
Examples of the use of these fields include:
- Setting the URL to be myserver.com/devices/[SERIAL] - so data from specific serials can be directed to the correct place.
- Sending a plant number or asset rego number etc as part of the payload so it can be matched up on the end platform.
- Per Device Authentication keys/tokens
Authentication, Authorization and Security
The latest generation of our devices connect to OEM over an AES-256 encrypted connection. After OEM, when transmitting to a 3rd party server, the HTTPS connector can be used to ensure complete end-to-end encryption.
Other authorization schemes can be accommodated, for example:
- Basic Authentication - Auth details are sent in the header of the POST
- Bearer Token Authentication
- Per device authentication - such as for the Azure IoT Hub. This makes use of the custom fields to store a key per device. The Azure-IOT Hub Helper can be used to easily load these keys into OEM.
What is Bearer Token Authentication?
When Device Manager sends device data to a 3rd party end platform over HTTP, a Bearer Token is a type of access token used for authentication and authorisation.
Here's how it typically works:
Authentication: When Device Manager wants to send data to the 3rd party end platform, it needs to prove its identity. It does this by attaching a bearer token to the HTTP request headers.
Bearer Token: The bearer token is a string of characters issued by the 3rd party end platform during the authentication process. This token serves as a credential for accessing the platform's resources. It's like a digital key that grants access.
Authorisation: When the 3rd party end platform receives the HTTP request with the bearer token, it checks the token's validity. If the token is valid, the platform allows the Device Manager to send the device data. If the token is invalid or expired, access is denied.
Security: Bearer tokens need to be kept secure because anyone with access to a valid bearer token can potentially access the associated resources. Therefore, they can be transmitted over HTTPS to encrypt the communication and prevent interception by unauthorised parties.
In summary, a bearer token is a means of authentication and authorisation, allowing Device Manager to securely access and transmit data to the user's end platform.