Secure Device Onboarding

If you currently onboard nRF91 Series devices by claiming them through legacy nRF Cloud Security Services, this guide explains how to migrate to the new nRF Cloud experience. It covers what replaces claiming and provisioning rules, and how to onboard a single device or a batch of devices with the nrfcloud CLI.

This guide covers nRF9151 and nRF9161 devices onboarded with an identity attestation token.

Claiming in legacy nRF Cloud continues to work during the transition, so you can move at your own pace.

What is changing

Claiming and onboarding were previously separate steps. You claimed a device with the Provisioning Service, and a provisioning rule optionally onboarded it to the rest of nRF Cloud. In the new nRF Cloud experience, adding a device does both: a successful add claims and onboards the device.

Nothing changes on the device during migration. You read the same identity attestation token with the same AT%ATTESTTOKEN command, and the nRF Cloud provisioning client installs credentials the same way. The provisioning client must be included in device firmware; for devices that already meet this requirement, no firmware or SDK change is required.

Aspect	Legacy nRF Cloud claiming	New nRF Cloud experience
Where you do it	Security Services → Claimed Devices	Fleet → Devices → Add devices, or the nrfcloud CLI
Authentication	API key	Organization auth token (OAT)
Scoping	Your nRF Cloud team	An organization and a project, both named in the URL
API host	api.provisioning.nrfcloud.com	api.nrfcloud.com
Device credential	Identity attestation token	Identity attestation token (unchanged)
Onboarding	Opt-in, configured with a provisioning rule	Automatic when the device is added
Grouping at add	Provisioning groups and tags	Cohorts; every device starts in the default cohort

Before you begin

To onboard devices with the CLI, you need:

• An organization auth token with the device:write permission. It replaces the API key you used for claiming. Organization admins create tokens under Admin → Organization Auth Tokens → Create Token. See Organization Auth Tokens.

• Your organization slug and project slug, both of which appear under Project Settings → General.

• The ID and attestation token for each device you want to onboard.

• The nrfcloud CLI, which is installed with the Memfault CLI, version 1.12.0 or later:

  pip install "memfault-cli>=1.12.0"

The following examples assume your OAT, organization slug, and project slug are available as the environment variables NRFCLOUD_OAT, NRFCLOUD_ORG, and NRFCLOUD_PROJECT, respectively. For a step-by-step walkthrough of this setup, see Onboarding Devices with the CLI.

Onboarding a single device

Where you previously opened Security Services → Claimed Devices and clicked Claim Device, you now go to Fleet → Devices → Add devices, choose the nRF91 Series, and paste the device's attestation token.

For the full walkthrough, see nRF91 Series Onboarding.

Onboard a device with the CLI

Read the device's UUID and attestation token:

AT%DEVICEUUID
%DEVICEUUID: cafe0001-0000-0000-0000-000000000001

OK
AT%ATTESTTOKEN
%ATTESTTOKEN: "2dn3hQHYJVDK_gABAAAAAAAA...0LcOMXU"

OK

Add them to a CSV, with the token copied without its quotes:

devices.csv

deviceId,attestationToken
cafe0001-0000-0000-0000-000000000001,2dn3hQHYJVDK_gABAAAAAAAA...0LcOMXU

Then create the device:

nrfcloud --org-token $NRFCLOUD_OAT \
         --org $NRFCLOUD_ORG --project $NRFCLOUD_PROJECT \
         device create --csv devices.csv

The CLI prints OK if the device was claimed and onboarded, or the reason it was not.

Onboarding devices in bulk

Bulk onboarding uses the same nrfcloud device create command with a CSV of several devices. The CLI uploads the CSV, follows the upload to completion, and reports the result for each device. It is the easiest way to automate onboarding on a production line or in CI. See Onboarding Devices with the CLI.

Prepare the CSV

The CSV format has changed, so a file you previously submitted for bulk claiming will not work as-is.

Previously, the file had no header row and carried one attestation token per row, with an optional second column of tags:

2dn3hQHYJVDK_gABAAAAAAAAAAAAAAABBlCxawC1AABAAIAAAAAAAAABUAMUJTZHWGl6i5ytvs_g8QI.0oRDoQEmoQRBIfZYQAjRLHhsQgxmlioY9eB9mABZkZGXZ8MLY6GTf1l1IZhlVGnENMB094_5kOKZ-4-28QMfS66ehrhzdenU0LcOMXU
2dn3hQHYJVDK_gACAAAAAAAAAAAAAAACBlCxawC1AABAAIAAAAAAAAACUAMUJTZHWGl6i5ytvs_g8QI.0oRDoQEmoQRBIfZYQOsABez9vm3PBPiYrIQRncrjFbVcFph_EkESWCiH0-oiNiVYhs0B0xM_wrv2dwy9ZMdqfJRYiRD9Sa29VaPyBE4

For nRF9151 and nRF9161 devices, the new format requires a header row and a deviceId column alongside the attestation token:

deviceId,attestationToken
cafe0001-0000-0000-0000-000000000001,2dn3hQHYJVDK_gABAAAAAAAAAAAAAAABBlCxawC1AABAAIAAAAAAAAABUAMUJTZHWGl6i5ytvs_g8QI.0oRDoQEmoQRBIfZYQAjRLHhsQgxmlioY9eB9mABZkZGXZ8MLY6GTf1l1IZhlVGnENMB094_5kOKZ-4-28QMfS66ehrhzdenU0LcOMXU
cafe0002-0000-0000-0000-000000000002,2dn3hQHYJVDK_gACAAAAAAAAAAAAAAACBlCxawC1AABAAIAAAAAAAAACUAMUJTZHWGl6i5ytvs_g8QI.0oRDoQEmoQRBIfZYQOsABez9vm3PBPiYrIQRncrjFbVcFph_EkESWCiH0-oiNiVYhs0B0xM_wrv2dwy9ZMdqfJRYiRD9Sa29VaPyBE4

Requirements:

• The header row is required. Columns may appear in any order. For the devices covered by this guide, include only deviceId and attestationToken.
• deviceId must match the device ID that the row's attestation token attests. If it does not, only that row fails.
• A request may contain at most 1000 data rows.
• There is no tags column. Onboarded devices start in the default cohort, and you can move them afterwards. See Cohorts.

Where the device ID comes from

The attestation token encodes the device's UUID, which is its deviceId. If you collect tokens on your production line with gather_attestation_tokens.py from nRF Cloud Utils, you already have it: the script records the IMEI, UUID, and attestation token for every device it reads. You can create the format above by selecting the required columns from attestation_tokens.csv; you do not need to collect the tokens again.

Note that claim_devices.py still submits to legacy nRF Cloud, so upload the new file yourself with nrfcloud device create as shown below.

Upload the CSV

Pass the file to nrfcloud device create:

nrfcloud --org-token $NRFCLOUD_OAT \
         --org $NRFCLOUD_ORG --project $NRFCLOUD_PROJECT \
         device create --csv devices.csv

The CLI uploads the CSV, waits for nRF Cloud to process it, and prints one line per device:

cafe0001-0000-0000-0000-000000000001: OK
cafe0002-0000-0000-0000-000000000002: Device ID mismatch with token

Error: 1 of 2 device(s) failed to create.

Review failed rows

Rows that report OK were onboarded. The command exits with a non-zero status if any device fails, so a script can detect failures. To recover, correct the failed rows and run the command again with a CSV containing only those rows.

Replacing Bulk Operation History

Legacy nRF Cloud listed previous bulk onboarding requests by bulk ops request ID on the Device Management → Bulk Operation History page. That page is no longer available. In the new nRF Cloud experience, you get the result of each bulk onboarding when you run it:

• With the CLI, nrfcloud device create --csv devices.csv --res results.csv prints the result for each device and writes it to results.csv. See Create the devices.

Keep the CLI results file if you need a record of each operation. Onboarded devices appear under Fleet → Devices.

For the full request and response reference, see Create nRF9x Devices in Bulk.

Deleting, unclaiming, and deactivating devices

In legacy nRF Cloud, deleting a device from Device Management removed it from the fleet but did not unclaim it from Security Services. While the device remained claimed, no other team could claim or onboard it. To fully remove and release a device, you therefore had to delete and unclaim it separately.

In the new nRF Cloud experience, the action you choose depends on whether you want to retain the claim:

Desired outcome	Legacy nRF Cloud	New nRF Cloud experience
Remove the device and allow another project to claim it	Delete the device, then unclaim it	Delete Device removes the device from the fleet and unclaims it
Remove the device but prevent another project from claiming it	Delete the device but leave it claimed	Deactivate removes the device from the fleet but keeps it claimed and blocked; it can be reactivated later

Both actions permanently remove the device's associated fleet data. Deactivation retains its claim so that the device can be reactivated later.

You can delete a device in the nRF Cloud application or with the API. To use the API, set DEVICE_ID to the device's ID and send the following DELETE request:

curl -X DELETE \
  "https://api.nrfcloud.com/v1/organizations/$NRFCLOUD_ORG/projects/$NRFCLOUD_PROJECT/long-range/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

See Delete an nRF9x Device. Deactivating a device is currently available only in the nRF Cloud application.

Endpoint mapping

Task	Legacy nRF Cloud	New nRF Cloud experience
Onboard one device	POST https://api.provisioning.nrfcloud.com/v1/claimed-devices	nrfcloud device create, POST https://api.nrfcloud.com/v1/organizations/<ORG>/projects/<PROJECT>/long-range/devices, or Fleet → Devices → Add devices in the nRF Cloud application
Onboard devices in bulk	POST https://api.provisioning.nrfcloud.com/v1/claimed-devices (text/csv)	nrfcloud device create, or POST https://api.nrfcloud.com/v1/organizations/<ORG>/projects/<PROJECT>/long-range/devices/bulk
Track a bulk upload	Results returned in the upload response	Not needed with nrfcloud device create; otherwise follow the URL returned in the 202 response
Authorization header	Authorization: Bearer <API_KEY>	Authorization: Bearer <OAT>

The legacy endpoints returned their results synchronously. The new single-device endpoint also returns its result synchronously, but the bulk endpoint accepts the upload and reports results asynchronously. Onboarding a batch requires one POST request followed by one or more GET requests; nrfcloud device create makes these requests for you.

Provisioning rules and groups

Provisioning rules and provisioning groups do not exist in the new nRF Cloud experience. Use the following equivalents:

• Auto-onboarding is no longer something you configure. Adding a device claims and onboards it.
• Provisioning groups and tags are replaced by cohorts. Every device starts in the default cohort and belongs to exactly one cohort at a time.

After onboarding

Devices appear under Devices within a few minutes. Each device page shows its Provisioning Status and the time it last checked in, so you can confirm that a newly onboarded device completed its credential exchange.

Troubleshooting

Symptom	Likely cause	Fix
401 Unauthorized	The OAT is missing or invalid	Recopy the OAT and confirm the header uses Bearer
403 Forbidden	The OAT lacks device write access	Ask an organization admin to create an OAT with the required permission
415 Unsupported media type.	The request was not sent as CSV	Send the file with Content-Type: text/csv
400 Missing CSV header.	The file has no header row	Add deviceId,attestationToken as the first line
400 Unrecognized CSV header: <name>.	A column name is not recognized	Remove leftover columns such as tags
400 Number of CSV rows exceeds the 1000 limit.	Too many rows	Split the file into batches of 1000 rows or fewer
400 This request exceeds your monthly quota…	The project's device limit was reached	Review your plan's device limit
Row error Can not verify token	The token is corrupted or was altered in transit	Re-read the token with AT%ATTESTTOKEN and resubmit that row
Row error Device ID mismatch with token	deviceId does not match the ID the token attests	Use the UUID encoded in that device's token
Row error Device is already claimed by another project	The device belongs to a different project	Remove it from the other project before trying again
Row validation error naming a row index	That row is missing deviceId or attestationToken	Fill in both values for the row

If a device still fails to onboard, contact support.

Questions or Feedback?

Reach out to us on the DevZone community forum.