Skip to content

Claiming device ownership through the APIs

This guide explains how to use the Provisioning Service for claiming device ownership using the APIs. See Claiming device ownership through the nRF Cloud portal if you want to use the portal instead.


To securely provision a device, you must provide a claim token.

To obtain a claim token, fetch an identity attestation token from your device. Claimed devices are then visible in the list of your claimed devices and are ready to be provisioned securely.


The Provisioning Service is available to Editor, Admin, and Owner roles.

Claiming ownership of a single device

Use the ClaimDeviceOwnership endpoint to claim ownership of a single device:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{ "claimToken": "2dn3hQFQSWHIc0CMRc6xunwNmdiBeQNQpNWAuar7SSW8jduV9zfUrlDi2RpLvSI7Lpj6UEpyjZUy.0oRDoQEmoQRBIfZYQOOK3tk8JPbQj97vYSUwvg2l4RWnI-HkW870dxWy6pirvWJ5ZfjLtJsP-R5C9MJNtMHkZEZNjI1bmMaMLInZWTE", \
      "tags": [ "location=Trondheim" ] }'

The response shows all attributes of the claimed device:

  "id": "7b21b4bc-1cc9-41df-b05c-61b4605e5bb0",
  "deviceType": "nrf9160_SICA",
  "firmwareId": "6100e43d-e06f-4017-9a5c-11550b8cc347",
  "imei": "352656106118683",
  "ownerId": "a5592ec1-18ae-4d9d-bc44-1d9bd927bbe9",
  "ownershipStatus": "IDENTIFIED",
  "tags": [ "location=Trondheim" ],
  "status": "READY",
  "claimedAt": "2023-06-13T14:17:14.352Z"

Claiming ownership of multiple devices

To claim ownership of multiple devices:

  1. Create a CSV file where each row contains one claim token.
  2. Upload the CSV file using the BulkClaimDeviceOwnership endpoint:

    curl -X POST \
    -H "Content-Type: text/csv" \
    -H "Authorization: Bearer $API_KEY" \

A successful request returns an HTTP 202 response with a bulkOpsRequestId, as in the following example:

  "bulkOpsRequestId": "01G4ACS60SAEK1YNGSSJHBEET0"

You can then see the result by fetching the operations status.

CSV requirements for bulk device ownership claiming

The CSV file containing tokens for bulk device ownership claiming must include each claim token on a separate row in the first column. The second column is optional and may contain tags as a comma-separated list:


Fetching bulk operation status

Once you have uploaded the CSV file, use the FetchBulkOpsRequest endpoint to fetch the status of your request:

curl \
-H "Authorization: Bearer $API_KEY"

The response contains the status of the request, which can be PENDING, IN_PROGRESS, FAILED or SUCCEEDED. If failed, the response contains an errorSummaryUrl from which you can see any errors:

  "bulkOpsRequestId": "01G4ACS60SAEK1YNGSSJHBEET0",
  "status": "SUCCEEDED",
  "requestedAt": "2023-06-30T11:49:21.561Z",
  "completedAt": "2023-06-30T11:49:21.652Z",
  "uploadedDataUrl": ""

Managing device groups

You can group claimed devices by adding tags to them. A tag can be maximum 100 characters.


Groups are referred to as tags in some APIs. Adding a new tag through the APIs adds a new provisioning group in the nRF Cloud portal.

Define the tags first using the Device Tag endpoints:

curl -X POST $API_HOST/v1/claimed-devices/tags -d '{ "tag": "location=Trondheim", "description": "Devices deployed in Trondheim." }' -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json"

You can list all tags or fetch details of a certain tag. See the following examples:

List details for all tags by sending a request without a filter:

curl -X GET $API_HOST/v1/claimed-devices/tags -H "Authorization: Bearer $API_KEY"

List tags for a specific device by including the device ID as a path parameter:

curl -X GET $API_HOST/v1/claimed-devices/tags/6c044228-4b96-4e65-9796-66b4b8bb0509 -H "Authorization: Bearer $API_KEY"

Use the UpdateTag endpoint to change the tag name and description:

curl -X PUT $API_HOST/v1/claimed-devices/tags/6c044228-4b96-4e65-9796-66b4b8bb0509 -d '{ "tag": "location=Trondheim", "description": "Devices deployed in Trondheim." }' -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json"


Changing a tag this way also changes the tag and description for any other devices with that tag.

When you delete a tag, it is automatically removed from all claimed devices. Use the DeleteTags endpoint:

curl -X DELETE $API_HOST/v1/claimed-devices/tags/6c044228-4b96-4e65-9796-66b4b8bb0509 -H "Authorization: Bearer $API_KEY"

Managing claimed devices

To list and manage your claimed devices, use the Claimed Devices API.

For example, use the ListClaimedDevices endpoint without optional filters to list all claimed devices associated with your account:

curl -X GET $API_HOST/v1/claimed-devices -H "Authorization: Bearer $API_KEY"

Blocking and unblocking devices

You can block or unblock a device. When a claimed device is blocked, it cannot connect to the Provisioning Service. Pending commands remain pending until the device can connect to the Provisioning Service again.

Use the BlockClaimedDevice endpoint to block a device, including the device ID as a path parameter:

curl -X POST $API_HOST/v1/claimed-devices/7b21b4bc-1cc9-41df-b05c-61b4605e5bb0/block -H "Authorization: Bearer $API_KEY"

Use the UnblockClaimedDevice endpoint to unblock the device, including the device ID as a path parameter:

curl -X POST $API_HOST/v1/claimed-devices/7b21b4bc-1cc9-41df-b05c-61b4605e5bb0/unblock -H "Authorization: Bearer $API_KEY"

This allows the device to run pending commands again.

Unclaiming a device


Use this endpoint to unclaim a device only if you intend to. Unclaiming a device means that another user or team can claim it and create a provisioning configuration for it. If you want to securely provision the device, you will need to claim it again.

Use the UnclaimDevice endpoint to forfeit your claim on the device:

curl -X DELETE $API_HOST/v1/claimed-devices/7b21b4bc-1cc9-41df-b05c-61b4605e5bb0 -H "Authorization: Bearer $API_KEY"

This releases the device and allows another user or team to claim it.

See next

For more information on how to fetch details, set tags, or unclaim a device, see the API documentation.