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.

Prerequisites¶

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.

Access

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 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:

Create a CSV file where each row contains one claim token.

Upload the CSV file using the BulkClaimDeviceOwnership endpoint:

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

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:

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

Fetching bulk operation status¶

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

curl https://api.provisioning.nrfcloud.com/v1/bulk-ops-requests/01G4ACS60SAEK1YNGSSJHBEET0 \
-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",
  "endpoint": "CLAIM_DEVICE_OWNERSHIP",
  "requestedAt": "2023-06-30T11:49:21.561Z",
  "completedAt": "2023-06-30T11:49:21.652Z",
  "uploadedDataUrl": "https://bulk.identity.nrfcloud.com/49fb25fd-812f-45ca-87ad-048587a10c12/claim_device_ownership/01G4ACS60SAEK1YNGSSJHBEET0.csv"
}

Managing device groups¶

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 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¶

Caution

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.