Skip to main content

Trustnetz Device Authorization API

This API service helps determine whether a device is allowed onto the network. It returns a decision of either whitelist or blacklist, depending on the device's properties and trust status. You can also update device properties through repeated requests. This is how a network interface would communicate with the CAHN system to use it to determine if a device should be trusted to onboard and stay connected to the network interface. THe policy used to determine ifa device is allowed to onboard is fully customisable by communicating via VCs to the claim cascade instance a particular trustnetz agent is connected to.

Endpoint​

POST /device-auth

Request Payload​

Send a JSON payload with the following structure:

{
    "id": "string",                    // Unique identifier for the device
    "name": "string (optional)",        // Human-readable name for the device (optional)
    "lorawan_device": { ... },           // LoRaWAN-specific properties (optional)
    "five_g_device": { ... },            // 5G-specific properties (optional)
    "wifi_device": { ... },              // Wi-Fi-specific properties (optional)
    "endpoint": "string"                // Callback URL provided by the network interface
}

Example Request​

{
    "id": "device-123",
    "name": "Temperature Sensor",
    "wifi_device": {
        "mac_address": "00:11:22:33:44:55"
    },
    "endpoint": "https://network-interface.local/callback"
}

Response​

The API will return a simple decision:

  • whitelist: The device is allowed onto the network.
  • blacklist: The device is denied access to the network.

Example response:

"whitelist"

Updating Device Information​

You can send a new POST request with the same id to update device properties (e.g., after firmware updates or configuration changes). The trust decision will be re-evaluated, and the updated decision will be sent to the network interface via the provided callback endpoint.

Callback to Network Interface​

When the decision changes, the Trustnetz agent will automatically notify the network interface using the endpoint URL:

{
    "id": "device-123",
    "decision": "blacklist" // or "whitelist"
}

This way, the network interface doesn’t need to poll the Trustnetz agent for updates. This gets checked every 1 second by default but is customisable in the trustnetz agent setup config.