OnboardDevices

Onboard and associate one or more devices with your nRF Cloud account by posting CSV data.

This endpoint supports two onboarding modalities depending upon whether you include device certificates or public keys in your CSV Payload.

Uploading a device certificate allows the device to use nRF Cloud services using any supported connectivity protocol, such as MQTT, and CoAP. This endpoint involves your own CA certificate and requires you to upload device certificates that you have already obtained, whether via a CSR produced by the AT%KEYGEN command (modem firmware v1.3+), or offline via your own script. We impose no rules on your CA certificate, and a self-signed certificate may be used. For more information see Onboarding in the nRF Cloud documentation.

Whether using our APIs via CoAP or MQTT you will need to flash to your device:

1. <a href="https://www.amazontrust.com/repository/AmazonRootCA1.pem" target="_blank">The Amazon Root CA1 PEM file</a>, which enables the device to authenticate the AWS IoT server.
2. The private key associated with the device certificate.

Additionally, if the device will be using MQTT, you will also need to flash the device certificate. For signing JWTs you will use the private key associated with the certificate. (During the device onboarding process we extract the corresponding public key from your uploaded certificate and use this for JWT signature verification.)

The second onboarding modality involves uploading a public key to verify the signatures of JSON Web Tokens (JWTs) sent by the device. Uploading a public key allows the device to use JSON Web Tokens (JWTs) signed by the private key of an asymmetric key pair, i.e., a private key that is different than the one used to sign the device's CSR (this key pair can be generated via the AT%KEYGEN command). If you are using JWTs signed by the device CSR key, and you have also uploaded the device's certificate via this or the OnboardDevices endpoint, there is no need to upload the public key, because it is automatically extracted from the certificate. This is useful for devices that only want to consume nRF Cloud services over REST.

Please note: Public keys must be ES256. For more information, see the nRF Cloud REST Authentication documentation.

This endpoint supports asynchronous bulk operations. Your data will be validated, and if valid, you will receive an HTTP 202 response with a bulkOpsRequestId. You can use this id with the bulk ops endpoints to track the request's processing status. If the bulk ops request indicates FAILED status, check the JSON errors file (URL in the bulk ops request details), fix the offending rows, then re-submit the CSV with only those rows.

Each CSV row must in the format deviceId,[subType],[tags],[supportedFirmwareTypes],"certificate", where:

Columns may appear in any order when a header row is present. If the header row is missing, the default column order is applied strictly: deviceId,subType,tags,supportedFirmwareTypes,certificate.

Examples of CSV rows:

All values set with certificate

<span style="font-family:Courier">deviceId,subType,tags,supportedFirmwareTypes,certificate<br/>f69c0e45-7f04-4949-8def-bb2215b4223e,my-thing-type,tag1|tag2,APP|MODEM,"-----BEGIN CERTIFICATE-----<br/>MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==<br/> -----END CERTIFICATE-----<br/>"</span>

subType not set

<span style="font-family:Courier">deviceId,tags,supportedFirmwareTypes,certificate<br/>f69c0e45-7f04-4949-8def-bb2215b4223e,tag1|tag2,APP|MODEM,"-----BEGIN CERTIFICATE-----<br/>MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==<br/> -----END CERTIFICATE-----<br/>"</span>

subType and tags not set, but supported supportedFirmwareTypes are set

<span style="font-family:Courier">deviceId,supportedFirmwareTypes,certificate<br/>f69c0e45-7f04-4949-8def-bb2215b4223e,APP|MODEM,"-----BEGIN CERTIFICATE-----<br/>MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==<br/> -----END CERTIFICATE-----<br/>"</span>

Using the public key modality

• <span style="font-family:Courier">deviceId,supportedFirmwareTypes,certificate<br/>f69c0e45-7f04-4949-8def-bb2215b4223e,APP|MODEM,""-----BEGIN PUBLIC KEY-----<br/>MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==<br/> -----END PUBLIC KEY-----<br/>"</span>

Without header row (default strict column order: deviceId,subType,tags,supportedFirmwareTypes,certificate)

• <span style="font-family:Courier">f69c0e45-7f04-4949-8def-bb2215b4223e,,tag1|tag2,,"-----BEGIN CERTIFICATE-----<br/>MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==<br/> -----END CERTIFICATE-----<br/>"</span>

Also note:

• Max number of rows is 1000.
• Do not leave any blank lines.

Example of uploading CSV data as a binary file:

curl -X POST $API_HOST/v1/devices \
--data-binary @$PATH_TO_CSV_FILE \
-H "Content-Type: application/octet-stream" \
-H "Authorization: Bearer $API_KEY"

Note that for some unknown reason, curl will strip the final line break in each ES256 cert when sending the CSV file using a non-binary content-type, e.g., using syntax such as -d @$PATH_TO_CSV_FILE -H "Content-Type: text/csv". Therefore, with curl use --data-binary only. If you want to send the CSV as text, use a REST client like Postman or Insomnia. To synchronously provision a single device, you can also use the OnboardDevice endpoint.

{
  "bulkOpsRequestId": "01EZZJVDQJPWT7V4FWNVDHNMM5"
}