Device Shadow

Existing device shadows automatically appear in the new nRF Cloud experience. The new and legacy experiences use the same shadow data, so you do not need to migrate device state or make firmware changes.

You can begin managing a shadow in the new experience without interrupting device communication. MQTT and CoAP devices continue to retrieve, update, and receive shadow changes through their existing connections.

REST API clients

If an integration uses a legacy nRF Cloud REST endpoint and API key, update it to use an organization auth token (OAT) and the new organization- and project-scoped endpoint. Device MQTT and CoAP credentials do not change.

What stays the same

• Existing reported, desired, and delta state carries over.
• Devices continue to use the same shadow and device credentials.
• MQTT topics and CoAP state endpoints do not change.
• A desired value remains pending until the device reports the requested value.
• Custom fields in the desired and reported state continue to work.

What changes for you

Task or setting	Legacy nRF Cloud	New nRF Cloud experience
Find a device	Device Management → Devices	Fleet → Devices
Open the shadow	Select a device → Shadow	Select a device → Device Shadow
View configuration	View Config	Device Config table
Edit configuration	Edit Configuration, optionally Copy Reported	Edit individual desired values, then click Save changes
View the complete state	Shadow tab	Device Shadow JSON
View access	Legacy nRF Cloud team access	A project role with device:read
Edit access	Legacy nRF Cloud team access	A project role with device:write
REST API authentication	nRF Cloud API key	OAT with Device Data access
REST URL scope	Device endpoint without organization and project path values	Organization- and project-scoped long-range device state endpoint

The new Device Config table omits platform-controlled, read-only desired settings. They remain visible in Device Shadow JSON.

Start using the new web app

1. Open Fleet → Devices.
2. Select an existing nRF Cloud device.
3. Select the Device Shadow tab.
4. Confirm that the expected reported and desired values appear.
5. If you have write access, change a desired value and click Push to device.
6. Confirm that the setting displays pending, then returns to a synchronized state after the device reports the requested value.

Opening or refreshing a shadow does not change it. You can continue to view the same data in legacy nRF Cloud during the transition.

For complete instructions, see Device Shadow.

Update a legacy REST integration

This section applies to external applications and scripts that retrieve or update shadows through the nRF Cloud REST API. It does not apply to devices that use MQTT or CoAP.

Before you begin

You need:

• The organization slug and project slug that contain the device.
• An organization auth token created for that organization and project. Select Device Data → Read to retrieve shadows or Device Data → Manage to retrieve and update them.
• The existing device ID.

Change authentication and URL

Continue to send requests to https://api.nrfcloud.com, but replace the legacy API key and URL with the OAT and scoped URL.

Operation	Legacy endpoint	New endpoint
Retrieve state	GET /v1/devices/<DEVICE_ID>	GET /v1/organizations/<ORG>/projects/<PROJECT>/long-range/devices/<DEVICE_ID>/state
Update state	PATCH /v1/devices/<DEVICE_ID>/state	PATCH /v1/organizations/<ORG>/projects/<PROJECT>/long-range/devices/<DEVICE_ID>/state

For legacy list requests that use GET /v1/devices?includeState=true, retrieve the state of each required device from its new device state endpoint.

For example, update a desired value with:

curl -X PATCH \
  "https://api.nrfcloud.com/v1/organizations/$NRFCLOUD_ORG/projects/$NRFCLOUD_PROJECT/long-range/devices/$DEVICE_ID/state" \
  -H "Authorization: Bearer $NRFCLOUD_OAT" \
  -H "Content-Type: application/json" \
  -d '{
    "desired": {
      "config": {
        "sampleInterval": 30
      }
    }
  }'

The new API accepts a partial desired or reported object and merges it into the existing state. Setting a key to null deletes it. The API validates platform-managed paths and value types.

See the API references for retrieving and updating device state.

Verify the updated integration

1. Retrieve a known device shadow with the new URL and OAT.
2. Confirm that the response contains the expected reported, desired, delta, metadata, and version fields.
3. Patch a non-critical writable desired value.
4. Retrieve the shadow again and confirm that the value appears in desired and, until the device applies it, in delta.
5. Confirm that the device reports the value and that it is removed from delta.

Troubleshooting

For web app and REST API errors, see Device Shadow troubleshooting.