Multicast Key Management

The Key Management API provides a centralized way to upload and manage multicast keys for devices in the FUOTA server. These keys are required for non-MachineQ devices that do not support automatic key generation. This guide covers the endpoints, the request formats, and why key management moved to a central location.

Before You Begin

You need:

• The DevEUIs and multicast keys (GenAppKey/McKey) for any non-MachineQ devices you plan to update.
• $MQ_TOKEN exported from the authentication step. See Quick Start Guide.

MachineQ Devices: For MachineQ MQmonitor, MQflex, and MQio devices, there is no need to upload keys. The FUOTA server automatically generates the required multicast keys using a device-specific key. For third-party devices, keys must be uploaded before including them in FUOTA campaigns.

Upload Keys

Upload keys with the upload keys API. The FUOTA server uses them later when campaigns are created or managed by the server.

curl -sS -X POST "https://fuota.machineq.net/api/v3.2/key_management" \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "0102030405060708": "01020304050607080102030405060708",
    "0011223344556677": "aabbccddeeffaabbccddeeffaabbccdd"
  }' | jq

The request body is a dictionary mapping DevEUIs to their multicast keys:

Delete Keys

Delete multicast keys for the provided devices with the delete keys API. The request body is a list of DevEUIs to delete.

curl -sS -X DELETE "https://fuota.machineq.net/api/v3.2/key_management" \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["0102030405060708", "0011223344556677"]' | jq

Why Centralized Key Management?

The centralized Key Management API replaces the previous approach of uploading keys in multiple places. It addresses several issues:

• Simplified key lifecycle management. Previously, keys could be provided via the /managed_campaign/upload_multicast_keys endpoint (tied to managed campaigns) or via the devices dictionary in /device_group payloads (only usable in a single campaign). This caused confusion about where keys were stored. The central API provides a single, clear location.
• Decoupled key storage from campaign/group creation. Keys can now be uploaded, updated, or deleted independently of campaign or device group operations, without recreating a device group.
• Consistent data format. The devices field is always a list of DevEUIs, and keys are managed separately, removing the previous polymorphic behavior.
• Better security and encryption support. Centralized storage uses encrypted storage by default: symmetric encryption (AES-128-CBC with HMAC), automatic migration of legacy unencrypted keys on access, and clear separation between encrypted and legacy storage.
• Support for key delegation. With centralized storage, the key lookup sequence is: the current subscriber's keys, then global device keys (for MachineQ-provisioned devices), then the delegating subscriber's keys. See Upgrade Delegation.

Deprecated APIs

POST /managed_campaign/upload_multicast_keys (Deprecated in v3.2)

This endpoint still functions but will be removed in a future major version. Migrate to POST /key_management. The request body format is identical.

# Old:
POST /api/v3.1/managed_campaign/upload_multicast_keys
# New:
POST /api/v3.2/key_management

Device Group devices Dictionary (Deprecated)

The devices field in device group creation/updates previously accepted a dictionary mapping DevEUIs to keys. It should now be a list of DevEUIs:

{
  "devices": ["0102030405060708", "0011223344556677"]
}

Note: All existing keys are automatically migrated to the centralized storage. Any new groups created using the old APIs (prior to v3.2) are also automatically migrated.

What's Next?

• Managed Campaigns: Use uploaded keys to run recurring campaigns on non-MachineQ devices.
• Upgrade Delegation: See how centralized keys enable delegated upgrades.
• Frequently Asked Questions: Learn more about GenAppKey and MachineQ keygen.