Please enable JavaScript to view this website.

Skip to main content
API docs by Redocly

Digital IoT Services REST API (0.0.0)

Download OpenAPI specification:Download

Overview

The Digital IoT Services REST API provides endpoints for provisioning, configuring, and managing cellular and WiFi connected IoT devices in the field.

Core functionality this API provides:

  • Certificates: Issue bootstrap certificates using device-generated Certificate Signing Requests (CSRs)
  • Device Shadows: Read and write device state via AWS IoT named shadows, including status metadata (e.g. battery level, signal strength) and configuration values

Who should use these endpoints?

  • Firmware engineers for adhoc provisioning of device certifications
  • Software teams building features that require interaction with devices in the field
  • Manufacturers trying to provision units and confirm functionality of devices on the line

Related Documentation

For information about MQTT topics, device shadows, and other platform capabilities, see the Remote Comms documentation.

Certificate Management

Operations for creating and managing X.509 certificates for IoT device provisioning. These endpoints enable secure device identity establishment using Certificate Signing Requests (CSRs) generated on the device itself without the private keys ever leaving the device.

These certificates enable direct-to-cloud communication with AWS IoT Core and are not to be confused with so-called MLS (multi-layer security) certificates which are used for encrypted BLE communication with the ONE-KEY mobile app.

Create a bootstrap certificate from a device-generated CSR

Creates and issues an X.509 bootstrap certificate for device provisioning using a Certificate Signing Request (CSR).

Who should use this endpoint?

This HTTP endpoint is used at the time of manufacturing to create a unique "boostrap" certificate for a single device. The bootstrap certificate is then used by the device to self-provision an operational certificate via MQTT.

Workflow

  1. [Pre-req] Device has gone through standard end-of-line programming and has recieved a unique MPBID.
  2. Device generates a private key and a corresponding CSR. The CSR is then sent to the programming utility.
  3. Programming utility sends the CSR to this endpoint along with MPBID and device type (e.g. "gateway" or "tool").
  4. API validates the request and issues a signed bootstrap certificate from our private Certificate Authority.
  5. Bootstrap certificate is stored on device and is used to authenticate with AWS IoT Core to self-provision an operational certificate via MQTT.

Security Model

This CSR-based approach ensures that private keys never leave the device. The device maintains full control of its private key throughout the provisioning process.

Request Requirements

The request body must contain:

  • mpbid: 10-character hexadecimal string uniquely identifying the device
  • deviceType: Type of device ("gateway" or, perhaps in the future, "tool")
  • certificateSigningRequest: PEM-encoded CSR generated on the device

Response Format

The response includes a single CreateCsrCertificateResponse object containing the certificate ID (64-character hex string), PEM-encoded certificate, and metadata needed for device authentication with AWS IoT Core.

Note: this bootstrap certificate grants the device only a limited set of permissions to AWS IoT Core. The device will need to self-provision an operational certificate via MQTT to gain access to all the AWS IoT Core resources it will need to interact wiht.

Authorizations:
auth0-authorizerjwt-authorizer
Request Body schema: application/json
required
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$

Unique 10-character hexadecimal string used as the device identifier. MPBID stands for "Milwaukee Product Binary Identifier" and serves as the primary identifier for devices across Milwaukee Tool's connected product ecosystem. This identifier is assigned during manufacturing and is used to associate certificates, device shadows, and other device metadata.

Encoding: The first 4 hex characters encode the product ID (0x0000–0xFFFF) and the last 6 hex characters encode the sequence/serial number (0x000000–0xFFFFFF).

Case: Always send uppercase. The pattern above allows both uppercase and lowercase hex characters — this is intentional, as the REST API accepts either case and normalizes the value to uppercase on input. However, the MQTT Fleet Provisioning pre-hook Lambda enforces strict uppercase and will reject requests containing lowercase characters. To avoid issues across both phases, always send uppercase.

Certificate subject: This value is embedded as the Given Name (GN) field in the X.509 certificate issued from the CSR.

deviceType
required
string (DeviceType)
Enum: "gateway" "tool"

Type of device for which the certificate is being issued. This field helps categorize devices and may influence certificate policies or device permissions in AWS IoT Core.

  • gateway: A gateway device that may aggregate or relay communications for other devices
  • tool: A power tool or other primary product device
certificateSigningRequest
required
string (CertificateSigningRequest) [ 500 .. 2000 ] characters ^-----BEGIN CERTIFICATE REQUEST-----\r?\n (?:...

PEM-encoded Certificate Signing Request (CSR) generated on the device. The CSR contains the device's public key and subject fields, and is signed with the device's private key. The private key must never leave the device — only the CSR should be transmitted.

The CSR must be generated using RSA 2048-bit keys with SHA-256 signing, and must include the following X.509 subject fields exactly:

Field OID Required Value
Common Name (CN) 2.5.4.3 Device type string assigned to your product (e.g. bridge). Contact the CPP team for the correct value.
Given Name (GN) 2.5.4.42 Device MPBID (10-character hex string, uppercase)
Organization (O) 2.5.4.10 Milwaukee Tool (must be exact — IoT policies validate this field)
Organizational Unit (OU) 2.5.4.11 Connected Products
Country (C) 2.5.4.6 US
State (ST) 2.5.4.8 WI
Locality (L) 2.5.4.7 Brookfield

If the Organization field does not equal Milwaukee Tool exactly, the device will be able to establish an MQTT connection after provisioning but all publish and subscribe operations will be denied by the IoT policy.

Responses

Request samples

Content type
application/json
Example

Example request payload to create a device certificate for a tool device. The CSR should be generated on the device using the device's private key.

{
  • "mpbid": "FFFFE00000",
  • "deviceType": "tool",
  • "certificateSigningRequest": "-----BEGIN CERTIFICATE REQUEST-----\nMIICVjCCAT4CAQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAK8vq5k5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5\nr5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5\nr5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5\nr5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5\nr5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5\nIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEBADswd6y1ZOrt5H0Hcuhc1J2hUV1AI2H6\n-----END CERTIFICATE REQUEST-----\n"
}

Response samples

Content type
application/json

Example response payload for creating a certificate using device-generated CSR. This is the standard response format when a single certificate is issued.

{
  • "certificateId": "3a5f7e0b18c94d2e9bfa8d7c9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
  • "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKL7wQ8O3uN3MA0GCSqGSIb3DQEBCQUAMEUxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMjMwMTAxMDAwMDAwWhcNMjQwMTAxMDAwMDAwWjBF\nMQswCQYDVQQGEwJVUzETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAK8vq5k5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r\n5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r\n5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r\n5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r\n5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r5K5r\nIDAQABMA0GCSqGSIb3DQEBCQUAA4IBAQCK8vq5k5r5K5r5K5r5K5r5K5r5K5r5K5\n-----END CERTIFICATE-----\n"
}

Asset Scan Ingest

What is an Asset Scan? Bridge devices periodically scan for nearby BLE-enabled products (e.g., OneKey tools). An asset scan payload contains a set of scanned advertisements plus the gateway's location at the time of the scan. This data is processed and then passed along to the Tool Location Service (TLS) system.

Submit asset scan payload

Submit BLE advertisement data collected by a bridge device along with location info about the bridge.

Different from other endpoints in these docs

This endpoint uses AWS IoT Core HTTPS publish, to provide devices an alternate protocol for uploading this data. Posting to this endpoint is functionally equivalent to sending messages to the dt/{mpbid}/asset_scan topic over MQTT (more details).

Key things to note:

  • Different base URL - Requests must be sent to the MQTT endpoint on port 8443 (e.g. - https://mqtt.{env}.iot.digital.milwaukeetool.com:8443/)
  • Device certificate auth - Requests must authenticate with mTLS using the device's operational X.509 certificate
  • Same payload over MQTT - The payload of the HTTPS request is identical to publishing a message to the dt/{mpbid}/asset_scan topic (more details).

Basic Ingest vs. standard publish

This endpoint supports two URL patterns that both deliver the payload to the same downstream pipeline:

Mode URL path
Basic Ingest (recommended) /topics/$aws/rules/dt_asset_scan_ingest/dt/{mpbid}/asset_scan
Standard publish /topics/dt/{mpbid}/asset_scan

Use Basic Ingest unless you have a specific reason not to. Basic Ingest routes the message directly to the IoT rule engine, bypassing the MQTT broker entirely. This avoids the per-message broker fee and is the pattern all production devices use.

The standard publish path routes through the MQTT broker first, which means the message is also visible to any broker subscribers (e.g. the IoT Core MQTT test client). This can be useful during development or debugging, but should not be used in production.

(Optional) Dry run mode

Set dryRun: true in your payload if you'd like to test uploading data without passing it along to the downstream, Tool Location Service system.

If not provided, dryRun is set to false and data is passed along to Tool Location Service by default.

Authorizations:
device-certificate
path Parameters
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$
Example: FFFF000001

The 10-character hexadecimal MPBID of the reporting device. Must match the mpbid field in the request body.

query Parameters
qos
integer
Default: 1
Enum: 0 1

Quality of Service. Use 1 for at-least-once delivery (recommended).

Request Body schema: application/json
required
timestamp
required
integer <int64>

Unix epoch seconds when payload was uploaded.

mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$

Unique 10-character hexadecimal string used as the device identifier. MPBID stands for "Milwaukee Product Binary Identifier" and serves as the primary identifier for devices across Milwaukee Tool's connected product ecosystem. This identifier is assigned during manufacturing and is used to associate certificates, device shadows, and other device metadata.

Encoding: The first 4 hex characters encode the product ID (0x0000–0xFFFF) and the last 6 hex characters encode the sequence/serial number (0x000000–0xFFFFFF).

Case: Always send uppercase. The pattern above allows both uppercase and lowercase hex characters — this is intentional, as the REST API accepts either case and normalizes the value to uppercase on input. However, the MQTT Fleet Provisioning pre-hook Lambda enforces strict uppercase and will reject requests containing lowercase characters. To avoid issues across both phases, always send uppercase.

Certificate subject: This value is embedded as the Given Name (GN) field in the X.509 certificate issued from the CSR.

sessionId
integer or null

Scan session identifier (optional).

dryRun
boolean
Default: false

If true, process payload but skip TLS API submission. Useful for testing.

required
object (LocationSources) non-empty

Location data from the device. At least one of gnssFix or lteInfo must be present to provide valid location information for the scanned tools.

required
object (XAds)

Aggregated BLE advertisement data block from the device. Contains an array of extended advertisement entries captured during a scan session.

Responses

Request samples

Content type
application/json

Example payload containing both GNSS fix and LTE cell tower data. This provides the most accurate location by combining satellite positioning with cell tower triangulation. Multiple xAd entries show tools at varying distances (indicated by RSSI).

{
  • "timestamp": 1704067200,
  • "mpbid": "FFFFE00003",
  • "sessionId": 12347,
  • "dryRun": false,
  • "location": {
    },
  • "xAds": {
    }
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Device Shadows

Device shadows are JSON documents that store device state in the cloud. They enable synchronizing state between the cloud and device, even when the device is offline.

Supported Shadows

  • identity (read-only): Device identifiers and manufacturing metadata
  • status (read-only): Current runtime health and telemetry
  • location (read-only): metadata about last known physical location
  • config (writable): Configuration for tool including location scanning (if supported)

How Shadows Work

Each shadow has desired state (what the cloud wants) and reported state (what the device has). When you update desired state via this API, AWS IoT Core sends the changes to the device via MQTT. The device applies the changes and updates its reported state.

CORS Support

All shadow endpoints return CORS headers to enable cross-origin requests from web browsers:

  • Access-Control-Allow-Origin: * - Allows requests from any origin
  • Content-Type: application/json - Response content type

Preflight OPTIONS requests are handled automatically by API Gateway for cross-origin requests.

List device shadows

Retrieves a list of all named shadows that exist for a specific device. This endpoint is useful for discovering what shadows are available before attempting to retrieve or update a specific shadow.

Who should use this endpoint?

Software teams and firmware engineers who need to discover what shadows exist for a device, debug shadow configurations, or build dynamic UIs that work with arbitrary shadows.

Authorizations:
auth0-authorizerjwt-authorizer
path Parameters
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$
Example: FFFF000001

Unique 10-character hexadecimal string used as the device identifier. MPBID stands for "Milwaukee Product Binary Identifier" and serves as the primary identifier for devices across Milwaukee Tool's connected product ecosystem. This identifier is assigned during manufacturing and is used to associate certificates, device shadows, and other device metadata.

Encoding: The first 4 hex characters encode the product ID (0x0000–0xFFFF) and the last 6 hex characters encode the sequence/serial number (0x000000–0xFFFFFF).

Case: Always send uppercase. The pattern above allows both uppercase and lowercase hex characters — this is intentional, as the REST API accepts either case and normalizes the value to uppercase on input. However, the MQTT Fleet Provisioning pre-hook Lambda enforces strict uppercase and will reject requests containing lowercase characters. To avoid issues across both phases, always send uppercase.

Certificate subject: This value is embedded as the Given Name (GN) field in the X.509 certificate issued from the CSR.

Responses

Response samples

Content type
application/json

Example response showing all named shadows that exist for a device.

{
  • "shadows": [
    ]
}

Get device shadow

Retrieves the complete shadow document for a named shadow on a specific device.

Who should use this endpoint?

This endpoint is used by software teams and firmware engineers to read the current state of a device shadow, including both desired state (what the cloud wants) and reported state (what the device currently has).

Named Shadows

Devices can have multiple named shadows. For example: identity, status, config, location, etc. Each named shadow maintains its own independent state document. Use the shadowName path parameter to specify which shadow to retrieve.

Authorizations:
auth0-authorizerjwt-authorizer
path Parameters
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$
Example: FFFF000001

Unique 10-character hexadecimal string used as the device identifier. MPBID stands for "Milwaukee Product Binary Identifier" and serves as the primary identifier for devices across Milwaukee Tool's connected product ecosystem. This identifier is assigned during manufacturing and is used to associate certificates, device shadows, and other device metadata.

Encoding: The first 4 hex characters encode the product ID (0x0000–0xFFFF) and the last 6 hex characters encode the sequence/serial number (0x000000–0xFFFFFF).

Case: Always send uppercase. The pattern above allows both uppercase and lowercase hex characters — this is intentional, as the REST API accepts either case and normalizes the value to uppercase on input. However, the MQTT Fleet Provisioning pre-hook Lambda enforces strict uppercase and will reject requests containing lowercase characters. To avoid issues across both phases, always send uppercase.

Certificate subject: This value is embedded as the Given Name (GN) field in the X.509 certificate issued from the CSR.

shadowName
required
string (ShadowName)
Enum: "identity" "status" "config" "location"
Example: status

The name of a device shadow. Each shadow stores different types of device state:

  • identity (read-only): Device identifiers and manufacturing metadata
  • status (read-only): Current runtime health and telemetry
  • config (writable): Device configuration: BLE scanning, MQTT, antennas, reporting cadence, location override
  • location (read-only): Last known physical location

Write Access Control:

  • Only config can be updated via PUT/PATCH operations through this API
  • All other shadows (identity, status, location) are read-only via the HTTP API
  • Read-only shadows can only be updated by the device itself via MQTT
  • Attempting to PUT or PATCH a read-only shadow returns HTTP 403 Forbidden with error code ERR0003
query Parameters
includeMetadata
boolean
Default: false

When true, includes per-field shadow metadata timestamps and the shadow document version in the response. Useful for debugging sync issues or understanding when specific fields were last updated.

Responses

Response samples

Content type
application/json
Example

Example response for retrieving a status shadow. This shows device health and connectivity-related state values. Note: Status is a read-only shadow, so desired is null.

{
  • "state": {
    },
  • "timestamp": 1704067200
}

Update device shadow desired state (full replacement)

Replaces the entire desired state of a writable shadow. Any fields not included will be removed. Only works for writable shadows.

Write Access Control:

  • Only writable shadows can be updated via this endpoint
  • Attempting to update read-only shadows (e.g. - identity, status, location) returns HTTP 403 Forbidden

Operation Behavior:

  • PUT performs a complete replacement of the desired state
  • Any existing desired state fields not included in the request will be removed
  • Use PATCH if you want to update only specific fields without removing others
Authorizations:
auth0-authorizerjwt-authorizer
path Parameters
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$
Example: FFFF000001

The 10-character hexadecimal MPBID (Milwaukee Product Binary Identifier) that uniquely identifies the device.

shadowName
required
string (ShadowName)
Enum: "identity" "status" "config" "location"
Example: status

The name of the shadow to update.

Request Body schema: application/json
required
required
ConfigShadow (object) (WritableShadow)

Shadow content for writable shadows. Currently only config is writable via the HTTP API.

Only shadows that can be safely modified by external systems are included here. Device identity, status, and location must be controlled exclusively by the device to maintain data integrity

One of
enabled
required
boolean

Master enable/disable for device functionality.

object (BleScan)

BLE asset scanning: which advertisements to collect, and on what schedule.

object (MqttConfig)

MQTT client and connection settings. These apply to all broker connections.

object (Antennas)

Antenna selection per radio.

object (Reporting)

Upload and check-in cadence. Each entry is a Schedule.

object (LocationOverride)

Manually pin device location, overriding device-derived location. This value is also read by the asset-scan ingest pipeline as a location source.

lat and lon must be set together, and both are required when enabled is true. Setting enabled: true without coordinates returns HTTP 400 with error code ERR0001.

Responses

Request samples

Content type
application/json

Example request for fully replacing the desired state of a config shadow using PUT. This replaces all desired state values with the provided values. This is the only writable shadow.

{
  • "desired": {
    }
}

Response samples

Content type
application/json

Example response after successfully updating a config shadow. The response includes the updated shadow document with a new timestamp.

{
  • "state": {
    },
  • "timestamp": 1704067300
}

Update device shadow desired state (partial)

Partially updates the desired state by merging provided values. Fields not included remain unchanged. Only works for writable shadows.

Write Access Control:

  • Only writeable shadows can be updated via this endpoint
  • Attempting to update read-only shadows (e.g. - identity, status, location) returns HTTP 403 Forbidden

Operation Behavior:

  • PATCH performs a partial update by merging the provided values
  • Existing desired state fields not included in the request remain unchanged
  • Use PUT if you want to completely replace the desired state
Authorizations:
auth0-authorizerjwt-authorizer
path Parameters
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$
Example: FFFF000001

The 10-character hexadecimal MPBID (Milwaukee Product Binary Identifier) that uniquely identifies the device.

shadowName
required
string (ShadowName)
Enum: "identity" "status" "config" "location"
Example: status

The name of the shadow to update.

Request Body schema: application/json
required
ConfigShadow (object) (WritableShadow)

Shadow content for writable shadows. Currently only config is writable via the HTTP API.

Only shadows that can be safely modified by external systems are included here. Device identity, status, and location must be controlled exclusively by the device to maintain data integrity

One of
enabled
required
boolean

Master enable/disable for device functionality.

object (BleScan)

BLE asset scanning: which advertisements to collect, and on what schedule.

object (MqttConfig)

MQTT client and connection settings. These apply to all broker connections.

object (Antennas)

Antenna selection per radio.

object (Reporting)

Upload and check-in cadence. Each entry is a Schedule.

object (LocationOverride)

Manually pin device location, overriding device-derived location. This value is also read by the asset-scan ingest pipeline as a location source.

lat and lon must be set together, and both are required when enabled is true. Setting enabled: true without coordinates returns HTTP 400 with error code ERR0001.

Responses

Request samples

Content type
application/json

Example request for partially updating the desired state of a config shadow using PATCH. Only the provided fields will be updated; other desired state fields remain unchanged. PATCH performs deep merge, so patching nested objects like ble_scan will preserve existing nested fields not included in the request.

{
  • "desired": {
    }
}

Response samples

Content type
application/json

Example response after successfully updating a config shadow. The response includes the updated shadow document with a new timestamp.

{
  • "state": {
    },
  • "timestamp": 1704067300
}

Retrieve shadows for multiple devices (batch)

Retrieves the specified shadow type for multiple devices in a single request. This is more efficient than making individual GET requests when you need to fetch the same shadow for many devices.

Who should use this endpoint?

Software teams building dashboards, fleet management tools, or any application that needs to display shadow data for multiple devices at once.

Request Format

The request body contains an array of MPBIDs (1-100 devices). All devices will have the same shadow type retrieved (specified in the path parameter).

Response Behavior

  • HTTP 200: All devices were successfully retrieved
  • HTTP 207 Multi-Status: Some devices succeeded, some failed (partial success)

The response always contains a results array with one entry per requested device (in the same order as the request) and a summary with counts.

Note on POST for Read Operations

POST is used instead of GET to support large arrays of MPBIDs in the request body, which would exceed URL length limits if passed as query parameters.

Authorizations:
auth0-authorizerjwt-authorizer
path Parameters
shadowName
required
string (ShadowName)
Enum: "identity" "status" "config" "location"
Example: status

The name of the shadow to retrieve for all devices.

query Parameters
includeMetadata
boolean
Default: false

When true, includes per-field shadow metadata timestamps and the shadow document version in each device's response. Useful for debugging sync issues.

Request Body schema: application/json
required
mpbids
required
Array of strings (MPBID) [ 1 .. 100 ] items [ items = 10 characters ^[0-9A-Fa-f]{10}$ ]

Array of device MPBIDs to retrieve shadows for (1-100 items).

Responses

Request samples

Content type
application/json

Example request for retrieving the same shadow type for multiple devices.

{
  • "mpbids": [
    ]
}

Response samples

Content type
application/json

Example response when all devices are successfully retrieved.

{
  • "results": [
    ],
  • "summary": {
    }
}

Patch shadows for multiple devices (batch)

Partially updates (patches) the desired state of device shadows for multiple devices in a single request. Each device can have its own patch payload, enabling efficient fleet-wide configuration updates.

Who should use this endpoint?

Software teams building fleet management tools, configuration deployment systems, or any application that needs to update device configurations in bulk.

Request Format

The request body contains an array of patches (1-100 items). Each patch specifies:

  • mpbid: The device to update
  • desired: The partial desired state to merge with existing state

Deep-Merge Behavior

Patch payloads are deep-merged with existing desired state:

  • Fields in the patch replace existing values
  • Fields not in the patch are preserved unchanged
  • Nested objects are merged recursively

Write Access Control

  • Only the config shadow can be patched
  • Attempting to patch read-only shadows (identity, status, location) returns HTTP 403 Forbidden

Response Behavior

  • HTTP 200: All patches were successfully applied
  • HTTP 207 Multi-Status: Some patches succeeded, some failed (partial success)

The response always contains a results array with one entry per requested patch (in the same order as the request) and a summary with counts.

Duplicate MPBIDs

Duplicate MPBIDs are not allowed in a single request. If the same MPBID appears multiple times, the request will be rejected with HTTP 400 and error code ERR0001. Merge your patches for each device before sending the request.

Authorizations:
auth0-authorizerjwt-authorizer
path Parameters
shadowName
required
string (ShadowName)
Enum: "identity" "status" "config" "location"
Example: status

The name of the shadow to patch (must be 'config').

Request Body schema: application/json
required
required
Array of objects (DevicePatch) [ 1 .. 100 ] items

Array of device patches (1-100 items).

Array ([ 1 .. 100 ] items)
mpbid
required
string (MPBID) = 10 characters ^[0-9A-Fa-f]{10}$

Unique 10-character hexadecimal string used as the device identifier. MPBID stands for "Milwaukee Product Binary Identifier" and serves as the primary identifier for devices across Milwaukee Tool's connected product ecosystem. This identifier is assigned during manufacturing and is used to associate certificates, device shadows, and other device metadata.

Encoding: The first 4 hex characters encode the product ID (0x0000–0xFFFF) and the last 6 hex characters encode the sequence/serial number (0x000000–0xFFFFFF).

Case: Always send uppercase. The pattern above allows both uppercase and lowercase hex characters — this is intentional, as the REST API accepts either case and normalizes the value to uppercase on input. However, the MQTT Fleet Provisioning pre-hook Lambda enforces strict uppercase and will reject requests containing lowercase characters. To avoid issues across both phases, always send uppercase.

Certificate subject: This value is embedded as the Given Name (GN) field in the X.509 certificate issued from the CSR.

required
ConfigShadow (object) (WritableShadow)

Shadow content for writable shadows. Currently only config is writable via the HTTP API.

Only shadows that can be safely modified by external systems are included here. Device identity, status, and location must be controlled exclusively by the device to maintain data integrity

Responses

Request samples

Content type
application/json

Example request for patching config shadows for multiple devices. Each device can have its own patch payload.

{
  • "patches": [
    ]
}

Response samples

Content type
application/json

Example response when all patches are successfully applied.

{
  • "results": [
    ],
  • "summary": {
    }
}