CoAP API

Devices connect to ThingsBoard Edge over CoAP the same way they connect to ThingsBoard CE — only the host differs. Point your CoAP client to the Edge node’s IP address or hostname.

Default ports: 5683 UDP (plain), 5684 UDP (DTLS)

Two authentication mechanisms are supported:

Access token — include the device access token as a path parameter in each request:

coap://{EDGE_HOST}/api/v1/{accessToken}/...

X.509 certificates — use a device certificate and key for DTLS on port 5684. See Transport configuration for DTLS setup.

To find a device’s access token: go to Entities → Devices, open the device, click Copy access token on the Device details tab.

The examples below use access token authentication.

Base URL: coap://{EDGE_HOST}/api/v1/{accessToken}

Supported payload formats:

{"key1": "value1", "key2": true}

[{"key1": "value1"}, {"key2": true}]

With a client-side timestamp (Unix milliseconds):

{"ts": 1451649600512, "values": {"key1": "value1", "key2": true}}

Without a timestamp, the server assigns the current time.

Publish example using coap-client:

coap-client -m post \
  coap://$EDGE_HOST/api/v1/$ACCESS_TOKEN/telemetry \
  -e '{"temperature": 42}'

Publish example using coap-cli:

coap post coap://$EDGE_HOST/api/v1/$ACCESS_TOKEN/telemetry \
  --payload '{"temperature": 42}'

Publish client-side attributes:

coap-client -m post \
  coap://$EDGE_HOST/api/v1/$ACCESS_TOKEN/attributes \
  -e '{"firmware_version": "1.2.0", "serial": "SN-001"}'

Read client-side and/or shared attributes. The response groups results by scope: {"client": {...}, "shared": {...}}. Choose which attributes to return with these query parameters:

A request without any query parameters returns all client-side and all shared attributes.

Example:

coap-client -m get \
  "coap://$EDGE_HOST/api/v1/$ACCESS_TOKEN/attributes?clientKeys=serial&sharedKeys=firmware_version"

Response:

{"client": {"serial": "SN-001"}, "shared": {"firmware_version": "1.2.0"}}

Subscribe to server-side RPC commands using the CoAP Observe option:

coap-client -m get -s 300 \
  coap://$EDGE_HOST/api/v1/$ACCESS_TOKEN/rpc

Send a client-side RPC:

coap-client -m post \
  coap://$EDGE_HOST/api/v1/$ACCESS_TOKEN/rpc \
  -e '{"method": "getTime", "params": {}}'

For DTLS connections use port 5684. DTLS settings are configured in tb-edge.conf via the CoAP transport variables — see Transport configuration.