Upgrade Delegation

The upgrade delegation feature allows one subscriber to manage the device upgrades of another subscriber. This guide covers the delegation model, the permissions it grants, and the API endpoints used to create, view, edit, and delete delegation records.

Before You Begin

You need:

• The subscriber ID of the subscriber you want to delegate to (delegate_to).
• The DevEUI patterns of the devices you want to allow the other subscriber to manage.
• $MQ_TOKEN exported from the authentication step. See Quick Start Guide.

Use Cases

• Subscriber A owns devices and gateways on their account, but some of Subscriber A's devices are manufactured and managed by Subscriber B. Subscriber B needs to update those devices.
• Subscriber A owns the gateways while Subscribers B, C, and D bring their own solutions to a site with Subscriber A's gateways. Each subscriber updates the devices they provisioned, and Subscriber A allows them to use their gateway for upgrades.

Warning: Gateway delegation is not supported yet. The second use case, where Subscriber A allows other subscribers to use their gateways, has not been implemented. If you would benefit from this feature, please contact Product and/or your Sales representative.

Glossary

• delegate_from — The subscriber who lets another subscriber (delegate_to) manage its device upgrades and/or use their gateways for upgrades.
• delegate_to — The subscriber who can manage other subscribers' device upgrades according to the delegation records.

Assumptions

• delegate_from does not want to manage firmware upgrades for an external vendor or create vendor MQcentral accounts.
• delegate_to cannot mix devices from different delegate_from subscribers (including mixing with their own devices).
• delegate_from does not need to see the resources created by delegate_to that include their devices (device groups, campaigns, reliable downlink jobs, etc.).
• There can be only one record from delegate_from to delegate_to. To change it, use a PATCH request to update the record.

Delegation Record Data Model

Permissions

When delegate_from delegates device upgrade management to delegate_to, delegate_to can:

• Create device groups with delegate_from devices.
• Add delegate_from devices to a device group and patch device groups with delegate_from devices.
• Create reliable downlink jobs with delegate_from devices.
• See the device versions of delegate_from (only the delegated devices). The device version API accepts an optional delegated_subscriber_id query parameter; when provided, the result includes all DevEUIs belonging to delegated_subscriber_id after applying the include_devices and exclude_devices filters.
• Run FUOTA campaigns for device groups with delegate_from devices.

Note: delegate_from devices are any devices that pass the include_devices and exclude_devices filter and belong to the delegate_from subscriber.

Important: The delegate_to subscriber cannot specify the gateways in a device group with delegated devices. The FUOTA server automatically chooses the best gateway for the delegated devices. See the Automatic Gateway Selection section below.

Managing Delegations

There are multiple Upgrade Delegation APIs to manage the records.

Create Delegation

To create the upgrade delegation, use a POST request with the following payload.

curl -sS -X POST "https://fuota.machineq.net/api/v3.2/upgrade_delegation" \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delegate_to": "mq61lp",
    "include_devices": ["2CC407..00000FF."],
    "exclude_devices": ["2CC407..00000FF1"],
    "expires_at": "2100-12-31T23:59:59Z"
  }' | jq

• delegate_to — The subscriber ID to whom you delegate upgrading devices on your subscriber.
• include_devices — A list of DevEUI patterns formatted like the version pattern. Each must be 16 characters, using only hex characters and . (the dot matches any character).
• exclude_devices — Uses the same format as include_devices but filters out any matching DevEUIs from the allowed list. It is applied after include_devices.
• expires_at — When the delegation record expires. After this date, delegate_to cannot perform the allowed actions.

Example: Suppose the current subscriber has five devices: 2CC4073100000FF5, 2CC4073300000FF1, 2CC4073500000FF1, 2CC4073300000FF2, and 2CC4079B00000FA8. Using the payload above, delegate_to may manage upgrades of 2CC4073100000FF5 and 2CC4073300000FF2. Devices 2CC4073300000FF1 and 2CC4073500000FF1 match exclude_devices, while 2CC4079B00000FA8 does not match include_devices.

Note: The delegation record is visible to both delegate_from and delegate_to, but only delegate_from can edit and delete it.

Get Delegations

List all delegation records using the List Upgrade Delegations API, or retrieve a specific record using the Get Upgrade Delegation API.

Edit Delegation

Edit a record using the Update Upgrade Delegation API. All fields are the same as the POST request, but all are optional; only the included fields are edited.

Note: When a record's include_devices/exclude_devices changes, any device groups, campaigns, and reliable downlink jobs containing devices that no longer match will continue to exist. However, any action on those resources except deletion is prohibited. For example, delegate_to cannot start or restart a campaign that contains DevEUIs no longer matching the new filters.

Delete Delegation

Delete a record using the Delete Upgrade Delegation API.

Note: When you delete a record, the existing resources with delegated devices continue to exist, but any action on them except deletion is prohibited. Only the subscriber who created the delegation record can edit and delete it.

Automatic Gateway Selection

When the campaign starts, the server performs an additional check for the devices in the current device group. It first looks at all the gateways the target devices can reach, then partitions the gateways by subscriber and chooses the group of gateways belonging to a single subscriber based on the total "score" of that group. The score is usually equivalent to the number of devices the gateways can upgrade and the connection quality to those devices. The algorithm can choose the gateway group belonging to delegate_from or delegate_to, but not both.

Note: The Managed Campaigns feature does not support upgrade delegation yet.

What's Next?

• Multicast Key Management: See how centralized keys support delegated upgrades.
• Gateway Selection: Learn how gateways are automatically chosen for delegated devices.
• Firmware Version Parsing: Understand the pattern format used for DevEUI filters.