Managing claimed devices using the APIs

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

Prerequisites

To securely provision a device, you must provide an identity attestation token.

Fetch an identity attestation token from your device. Claimed devices are then visible to those with access and are ready to be provisioned securely.

Access

The Provisioning Service is available to editor, admin, and owner roles. Some operations are also available to viewers. See the API documentation for more information. Access by role depends on the feature.

Claiming ownership of a single device

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

curl -X POST https://api.provisioning.nrfcloud.com/v1/identities/claimed-devices \
-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, call the same endpoint as for a single device, but use a Content-Type of text/csv to pass multiple values:

1. Create a CSV file where each row contains one attestation token.

2. Upload the CSV file using the ClaimDeviceOwnership endpoint:

   curl -X POST https://api.provisioning.nrfcloud.com/v1/claimed-devices \
   -H "Content-Type: text/csv" \
   -H "Authorization: Bearer $API_KEY" \
   -d @$PATH_TO_CSV_FILE

A correctly formatted request returns an HTTP 200 response, regardless of whether all devices were successfully claimed. The results of the operation are in the response body in JSON format. For successfully claimed devices, the response shows their attributes. The failed array indicates the rows of the CSV file that correspond to any failed devices.

CSV requirements for bulk device claiming

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

2dn3hQFQMGctS_s1SFah9Ec8pTovDQNQJQ6Xd9jnSmyoRTcyiJBnpFDeHvNg-5iCpT8LJcf7JVzK.oRDoQEmoQRBIfZYQIa6SNb3Ic7oz1UCacFTgWc63TNOE8i3rEa-cZElEUrKOOHlJ0dwGwPvZY0FXcA5L3Zh-TfQBONj1N5LPqYMmJc,"Oslo,white"

Managing groups and tags

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

note

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"

note

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 added to your team:

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

Caution

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.