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 batch of devices with the API.

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. You read the same identity attestation token with the same AT%ATTESTTOKEN command, the provisioning client installs credentials the same way, and 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 nRF Cloud API
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

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 Device Onboarding.

note

Use the nRF Cloud application to add one device at a time. The nRF Cloud API reference does not currently document a single-device endpoint. To onboard devices programmatically, use the bulk endpoint below, which accepts a CSV with as few as one data row.

Onboarding devices in bulk

Bulk onboarding is available through the nRF Cloud API.

Before you begin

You need:

An organization auth token. Only organization admins can create one. See Organization Auth Tokens.
Your organization slug and project slug, both of which appear under Project Settings → General.
The attestation token and device ID for every device you want to onboard.

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 as shown below.

Upload the CSV

The following examples assume your OAT, organization slug, and project slug are available as NRFCLOUD_OAT, NRFCLOUD_ORG, and NRFCLOUD_PROJECT, respectively.

Post the file to the bulk endpoint:

curl -X POST \
  "https://api.nrfcloud.com/v1/organizations/$NRFCLOUD_ORG/projects/$NRFCLOUD_PROJECT/long-range/devices/bulk" \
  -H "Authorization: Bearer $NRFCLOUD_OAT" \
  -H "Content-Type: text/csv" \
  --data-binary @devices.csv

A 202 Accepted means the file was parsed and accepted. Device creation has not started yet. The response carries the URL to follow:

{
  "bulkOpsRequestId": "01EZZJVDQJPWT7V4FWNVDHNMM5",
  "url": "/v1/organizations/acme/projects/demo/bulk-ops-requests/01EZZJVDQJPWT7V4FWNVDHNMM5"
}

The Location response header contains the same value as url. Store either value as UPLOAD_URL.

Follow the upload to completion

Send GET requests to that URL until status is no longer IN_PROGRESS:

curl "https://api.nrfcloud.com$UPLOAD_URL" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

status is one of:

Status	Meaning
`IN_PROGRESS`	Rows are still being processed.
`SUCCEEDED`	Every row was onboarded.
`FAILED`	At least one row was not onboarded.

Always use the URL returned to you. Its structure is not part of the API contract and may change.

Review failed rows

On FAILED, an errorSummary object lists only the rows that did not onboard:

{
  "status": "FAILED",
  "requestedAt": "2026-08-19T12:00:00Z",
  "completedAt": "2026-08-19T12:00:04Z",
  "errorSummary": {
    "errorCount": 1,
    "errors": [
      {
        "row": 1,
        "deviceId": "cafe0002-0000-0000-0000-000000000002",
        "error": "Can not verify token"
      }
    ]
  }
}

row is the line number in the CSV you uploaded. The header is row 0, so data rows start at 1.

Rows absent from errorSummary were onboarded. To recover, correct the listed rows and submit a new CSV containing only those rows.

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.

Deleting and deactivating devices are 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`	nRF Cloud application: Fleet → Devices → Add devices
Onboard devices in bulk	`POST https://api.provisioning.nrfcloud.com/v1/claimed-devices` (`text/csv`)	`POST https://api.nrfcloud.com/v1/organizations/<ORG>/projects/<PROJECT>/long-range/devices/bulk`
Track a bulk upload	Results returned in the upload response	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 bulk endpoint accepts the upload and reports results separately, so onboarding a batch now requires one POST request followed by one or more GET requests.

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.

What is changing​

Onboarding a single device​

Onboarding devices in bulk​

Before you begin​

Prepare the CSV​

Upload the CSV​

Follow the upload to completion​

Review failed rows​

Deleting, unclaiming, and deactivating devices​

Endpoint mapping​

Provisioning rules and groups​

After onboarding​

Troubleshooting​

Questions or Feedback?​