CoAP

This page describes the CoAP connectivity in more detail

The Constrained Application Protocol (CoAP) (RFC 7252) is a specialized web transfer protocol designed for resource-constrained devices and networks. Operating over UDP, CoAP provides a low-overhead alternative to TCP/HTTP, making it ideal for IP-based IoT devices that require minimal power and bandwidth consumption.

To connect a CoAP-enabled device to akenza, you must first create a CoAP Device Connector and assign it to a Data Flow (Create Data Flow > Start with empty Data Flow > + Device Connector > CoAP > New CoAP Device Connector).

• For Pre-shared Key Authentication: a unique secret is generated upon creating the connector. Your device must pass this secret and the Device ID as query parameters in every CoAP request.

• For Secure X.509 Authentication: devices authenticate cryptographically via DTLS. You must submit your Custom Certificate Authority (CA) to akenza and provision devices matching the certificates, as detailed in the setup guide below.

By default CoAP communication without DTLS is insecure. Even if data transmission over a NB-IoT network is inherently encrypted within the cellular network, once the data leaves the carrier network for the public internet, additional measures are required to maintain security.

Therefore, we recommend using DTLS to secure the connection (see below). If your device does not support DTLS, the following alternative architecture can be implemented.

Fallback Architecture: Secure Tunnel

1. Private APN: Use a private APN configured by your network operator.

2. VPN Tunnel: Establish a secure VPN tunnel between the operator's APN and akenza.

3. Result: Data remains in its lightweight UDP format for the device, while the "hop" over the public internet is protected from eavesdropping by the tunnel.

Contact akenza for more information regarding transport security.

Secure Transport (DTLS)

To secure communication over unencrypted UDP networks, akenza supports Datagram Transport Layer Security (DTLS). This ensures confidentiality, data integrity, and secure device authentication.

X.509 Certificate Authentication

Devices can authenticate securely with akenza using X.509 Certificates. During the DTLS handshake, the device presents its cryptographic certificate to verify its identity, establishing an encrypted channel before any CoAP requests are transmitted. akenza will automatically extract the deviceId from the common name (CN) in the certificate.

To utilize X.509 certificate authentication, you must generate a Device Certificate Authority (CA) and individual Device Client Certificates for your devices. For more information, refer to DTLS Device Client Certificates.

Verifying the server identity

akenza uses server certificates issued by ZeroSSL. Make sure your devices trust the Sectigo Root Certificates specifically ZeroSSLECCDVSSLCA2.crt.

DTLS with Connection ID (CID)

To avoid costly DTLS handshakes after periods of inactivity, the protocol uses DTLS Connection IDs (as defined in RFC 9146). The CID allows the DTLS session to be resumed without a full handshake even when the device's IP address or UDP port changes (e.g., after a network sleep cycle).

The device aims to perform as few handshakes as possible. The DTLS session is kept alive across transmission intervals by using the CID, so a new handshake is only required when the session cannot be resumed.

Content Formats

The akenza CoAP connector supports multiple payload formats. Ensure your device includes the correct Content-Format option header in its requests to match the transmitted data type:

50	application/json	Standard JSON payload, parsed directly into a structured JSON object. If JSON parsing fails: Valid UTF-8 payload: Converted to plain text (value) plus Hex (payloadHex) and Base64 representations (payloadBase64). Invalid UTF-8 payload: Converted to Hex (payloadHex) and Base64 representations (payloadBase64).
60	application/cbor	Concise Binary Object Representation (CBOR). Parsed and converted into standard JSON.
41	application/xml	XML payload, automatically converted into a JSON structure.
42	application/octet-stream	Raw binary data. Automatically converted into both Hex (payloadHex) and Base64 (payloadBase64) string representations for the decoder.
0	text/plain	Plain text. The raw string is placed into a JSON object under the key value. Note that the string is expected to have utf-8 format.

Additional devices

akenza provides dedicated support for Efento devices.

Sending a CoAP Uplink

POST coap://coap.akenza.io:5683/v3/capture?secret={uplinkSecret}&deviceId={deviceId}

The body can be any JSON object.

Query Parameters

Name	Type	Description
timestamp	string	The timestamp of the event (ISO-8601 formatted - the current time will be used if not provided)
topic	string	The data topic ("default" will be used if not provided)
uplinkSecret	string	The uplink secret used to authenticate the request
deviceId	string	The device ID

Headers

Name	Type	Description
content_format	number	application/json

201 Note that the actual response code is 2.01 for CoAP

{
    "id": "UUID",
    "timestamp": "ISO-8601 date string",
    "message": "uplink received"
}

Sample NodeJS Script

The below sample nodeJS script allows sending a CoAP uplink. It requires the node module coap to be installed.

const coap = require('coap');

// define connection options
const options = {
    hostname: "coap.akenza.io",
    port: 5683,
    method: "POST",
    pathname: "/v3/capture",
    query: "secret={secret}&deviceId={deviceId}",
    options: {
        "Content-Format": "application/json",
    },
};
// create the request object
const req = coap.request(options);
// set the payload
const payload = {
    temperature: Math.random() * 100,
};
req.write(JSON.stringify(payload));
// handle success response
req.on('response', function (res) {
    res.pipe(process.stdout);
});
// handle error response
req.on('error', function (err) {
    console.log("error while sending coap request", err);
});
// send the request
req.end();