Prerequisites & Manufacturing Setup
Who should read these docs?
Manufacturing engineers setting up or integrating with the assembly line, and firmware engineers configuring region-specific endpoints for a SKU. Read this before starting Phase 1.
Before starting the device provisioning process, ensure you have the following credentials, tools, and endpoint information, and that the manufacturing prerequisites are in place.
Required Credentials
Auth0 Client Credentials
To obtain bootstrap certificates via the REST API, you need Auth0 client credentials for machine-to-machine authentication:
| Credential | Description |
|---|---|
client_id | Your Auth0 application client ID |
client_secret | Your Auth0 application client secret |
audience | The API audience URL (environment-specific, see table below) |
Contact the CPP Identity & Remote Comms team to request Auth0 client credentials for your manufacturing or development environment.
AWS IoT Root CA Certificate
For mTLS, the firmware must validate the server side of the TLS handshake. This requires the AWS IoT Root CA certificate to be bundled into the firmware or stored in non-volatile memory alongside the device certificates.
Use AmazonRootCA1 (RSA 2048-bit). Download it from the AWS CA certificates page. The file is approximately 1.2 KB in PEM format.
Some TLS stacks allow you to disable server certificate validation for development convenience. Never ship firmware with validation disabled. Without it, the device is vulnerable to man-in-the-middle attacks and cannot verify it is talking to the correct AWS IoT endpoint.
The Root CA certificate is the same across all CPP environments (dev, test, staging, prod) and all regions. Bundle one copy in your firmware image.
Tools and Libraries
The libraries listed below are used in the reference implementation. They are not requirements. Your product may use a different language, a bare-metal TLS stack, or a vendor-supplied SDK. What matters is meeting the protocol requirements described here, not which library you use to meet them.
CSR Generation
The CSR must be a valid PEM-encoded PKCS#10 Certificate Signing Request containing the subject fields listed below. How you generate it depends on your platform:
| Library | Language | Notes |
|---|---|---|
| cryptography | Python | Used in the reference implementation and code examples on this page |
| OpenSSL | C/C++ | Common choice for Linux-based systems |
| mbedTLS | C | Common choice for bare-metal embedded systems |
| Any X.509 / PKCS#10 library | Any | Any library that produces a valid PEM-encoded CSR will work |
CSR Subject Fields
The device must generate a CSR containing these X.509 subject fields exactly. The Common Name and Given Name fields are device-specific; all others are fixed values.
These requirements are the same for all CSRs regardless of type of certificate being requested.
| Field | OID | Value |
|---|---|---|
| Common Name (CN) | 2.5.4.3 | Device type string (e.g., bridge). Contact the CPP team for your product's value. |
| Given Name (GN) | 2.5.4.42 | MPBID (10-character hex string) unique for each unit |
| Organization (O) | 2.5.4.10 | Milwaukee Tool |
| 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 |
MQTT Client
Fleet Provisioning (Phase 2) requires an MQTT 3.1.1 client with mTLS support. The reference implementation uses the python AWS IoT Device SDK, but any compliant MQTT client works:
| Library | Language | Notes |
|---|---|---|
| awsiotsdk + awscrt | Python | Used in the reference implementation |
| AWS IoT Device SDK for C++ | C++ | Good starting point for Linux-based devices |
| mbedTLS + a MQTT client | C | Common choice for bare-metal embedded systems |
| Any MQTT 3.1.1 client with mTLS | Any | Must support mutual TLS and SNI |
These requirements apply regardless of library choice:
- Key type: RSA only. ECDSA is not currently supported by the CPP Certificate Authority.
- RSA key size: 2048 bits minimum
- Signature algorithm: SHA-256
- TLS: mutual authentication (mTLS) with SNI (Server Name Indication) enabled. SNI is a TLS extension that tells the server which hostname the client is connecting to during the handshake. The CPP MQTT endpoints require it. Most TLS stacks send it automatically, but some bare-metal implementations have it disabled by default and need it explicitly enabled.
- MQTT port: 8883
- Private keys must never leave the device. Generate keys on-device and only transmit the CSR.
Environment-Specific Endpoints
REST API Endpoints
When interacting with the REST API, you must provide a machine-to-machine JWT Bearer token. Use the following endpoints when requesting an auth token.
| Environment | API Base URL | Auth0 Token URL |
|---|---|---|
| DEV | https://api.dev.iot.digital.milwaukeetool.com | https://idtest.milwaukeetool.com/oauth/token |
| TEST | https://api.test.iot.digital.milwaukeetool.com | https://idtest.milwaukeetool.com/oauth/token |
| STAGING | https://api.staging.iot.digital.milwaukeetool.com | https://id.milwaukeetool.com/oauth/token |
| PROD | https://api.prod.iot.digital.milwaukeetool.com | https://id.milwaukeetool.com/oauth/token |
The full list of available endpoints and how to use them can be found within the HTTPS API documentation.
MQTT Endpoints (AWS IoT Core)
Use these endpoints for MQTT connections during Fleet Provisioning and Normal Operations over MQTT. The table below shows North America endpoints; see the regional table below for EU and Asia Pacific variants.
| Environment | MQTT Endpoint (North America) | Port |
|---|---|---|
| DEV | mqtt.dev.iot.digital.milwaukeetool.com | 8883 |
| TEST | mqtt.test.iot.digital.milwaukeetool.com | 8883 |
| STAGING | mqtt.staging.iot.digital.milwaukeetool.com | 8883 |
| PROD | mqtt.prod.iot.digital.milwaukeetool.com | 8883 |
Firmware must be configured with the endpoint that matches the product's intended region of sale. A device connecting to the wrong regional endpoint will fail to provision.
| Region | Domain Suffix | Example MQTT Endpoint (prod) |
|---|---|---|
| North America | digital.milwaukeetool.com | mqtt.prod.iot.digital.milwaukeetool.com |
| Europe | digital.milwaukeetool.eu | mqtt.prod.iot.digital.milwaukeetool.eu |
| Asia Pacific | digital.milwaukeetool.com.au | mqtt.prod.iot.digital.milwaukeetool.com.au |
Confirm the target region with the CPP team before end-of-line programming so the correct endpoint is configured in firmware for the SKU being manufactured.
The full list of available topics and how to use them can be found within the MQTT documentation.
Device Storage Requirements
Plan your NVM layout before starting firmware integration. The table below covers everything the firmware must persist across power cycles.
| Item | Format | Approx. Size | Mutability |
|---|---|---|---|
| AWS IoT Root CA certificate | PEM or DER | ~1.2 KB | Write-once (bundled in firmware image or NVM) |
| Bootstrap private key | PEM or DER | ~1.6 KB | Write-once at Phase 1; never replaced |
| Bootstrap certificate | PEM or DER | ~1.5 KB | Write-once at Phase 1; never replaced |
| Operational private key | PEM or DER | ~1.6 KB | Replaced on each certificate rotation |
| Operational certificate | PEM or DER | ~1.5 KB | Replaced on each certificate rotation |
| Provisioning state | enum (1 byte) | 1 B | Updated at each provisioning phase |
| Rotation job ID | string | ~64 B | Written when a rotation job is claimed; cleared after reporting SUCCEEDED/FAILED |
| Rotation execution number | uint32 | 4 B | Written when a rotation job is claimed; cleared after reporting SUCCEEDED/FAILED |
Total NVM budget: approximately 8–10 KB for certificates and keys, plus state variables.
Device Requirements
Before provisioning, each device must have:
- Unique MPBID: A 10-character hexadecimal Milwaukee Product Binary Identifier assigned during end-of-line programming
- Device Type: The device type string for your product (contact CPP team for the correct value)
- Secure Storage: Capability to securely store private keys and certificates
- Network Connectivity:
- HTTP/HTTPS access for REST API calls (manufacturing)
- MQTT over TLS (port 8883) for Fleet Provisioning (runtime)
Manufacturing Line Setup
Before the certificate REST API will accept a request for a given MPBID, a tool record for that device must already exist in the JEDI manufacturing records system. The certificate API validates the MPBID against this system on every call. A 404 error means the tool record hasn't been created yet, not that your request is malformed.
Tool Record Creation
The manufacturing line must submit a tool record to the JEDI manufacturing API. This is a separate step that happens at a different station on the assembly line, before IoT Device Provisioning.
The tool record links the device's MPBID to its product metadata (product ID embedded in MPBID, born-on date, passwords, firmware version, etc.) and propagates the registration to OneKey. Once a tool record exists, the certificate API will accept provisioning requests for that MPBID.
The Certificate API returns HTTP 404 if the MPBID is not found in the tool records system. Do not attempt certificate provisioning until the unit has gone through "OneKey end-of-line programming" to receive a unique unit-specific MPBID.
Get Help
- Teams: #digital-cpp-support
- Service Now: Open a ticket