nRF Cloud REST API (v1)

Fetch information about your team (also known as tenant), your team's current plan, and your user role and permissions for that team. Only team owners are allowed to view current month costs. The API key you use as the Bearer token in this request is specific to one team. You have one API key for each team of which you are a member.

Creates a new service key pair for authenticating REST endpoints that support JWTs. The public key is stored in nRF Cloud for use in JWT verification. The response contains the private key and a JWT signed by it, with a one year expiry. The private key can be used to generate additional JWTs with an expiry of your choice.

Gets the service token. The returned token is usable for all services.

List all team tags for your account.

Generates a JSON Web Token (JWT) for evaluating nRF Cloud Location Services by proxy servers. You may use this token to authenticate proxy server requests to any of the Location Service endpoints that indicate Service Evaluation Token among their Authorizations.

Calling this endpoint for the first time will start your 30-day evaluation period, after which you will need to contact Nordic Sales if you want to extend your evaluation period, or enter into a business agreement for commercial cloud-to-cloud use.

The JWT claims are set automatically by nRF Cloud when this token is generated. Although it can be regenerated upon request, the initial 30-day trial period remains unchanged.

For more information see JWT authentication for nRF Cloud.

Returns an existing Service Evaluation Token. Calling this endpoint will not start your evaluation period. You may create one by calling the GenerateServiceEvaluationToken endpoint.

Fetch a list of devices associated with the team defined by your API key.

Delete a device from your account. If you are attempting to delete a Nordic hardware product that was onboarded but not yet added to your account (associated), you must also pass the ownership code (PIN or HWID on the product label) in the request body. This will forward a DEVICE DISCON message on the /c2d MQTT topic, allowing the device to gracefully disconnect. You can view the format here.

curl -X DELETE $API_HOST/v1/devices/$DEVICE_ID -d $DEVICE_OWNERSHIP_CODE -H "Authorization: Bearer $API_KEY" -H "Content-Type: text/plain"

Fetch a device and its state.

curl $API_HOST/v1/devices/$DEVICE_ID -H "Authorization: Bearer $API_KEY"

List all device tags (groups) for your account.

Update the device name. The default name is the same as the device id.

Update a device's tags. Useful for labeling, categorizing, grouping, etc.

Update the image associated with a device, as displayed on nrfCloud.com. If uploading an image, add image to the request body (JPEG or PNG only). Otherwise, use the sourceUrl query param to set the device image to an existing image on the Web.

For a Web URL of an image associated with a device, dissociate the URL from the device. For an image file stored for a device, delete the image file.

Provision a device and attach an IoT policy with permissions that grant access to MQTT topics for any device in your team. This type of device can be useful in apps that need an MQTT client to monitor the messages on other devices, or for debugging and testing purposes. When a new team device (and subsequent certificate) is created, both the public AND private keys are returned. If the private key is lost, the certificate should be rotated to obtain a new public/private key pair.

Retrieve the team device certificate if it exists.

Create and attach a new certificate for a team device. Overwrite any previously associated certificate.

Delete a team device and its associated certificate.

Add a device to your nRF Cloud account. The association process is idempotent. You may therefore use this endpoint to update your device's subType. For more on the use of subType see the OnboardDevices endpoint.

curl -X PUT $API_HOST/v1/association/$DEVICE_ID -d "$DEVICE_OWNERSHIP_CODE" -H "Authorization: Bearer $API_KEY" -H "Content-Type: text/plain"

Onboard and associate one or more devices with your nRF Cloud account by posting CSV data.

This endpoint supports two onboarding modalities depending upon whether you include device certificates or public keys in your CSV Payload.

Uploading a device certificate allows the device to use nRF Cloud services using any supported connectivity protocol, such as MQTT, and CoAP. This is the recommended method for onboarding devices. Unlike the CreateDeviceCertificate endpoint, this endpoint involves your own CA certificate and requires you to upload device certificates that you have already obtained, whether via a CSR produced by the AT%KEYGEN command (modem firmware v1.3+), or offline via your own script. We impose no rules on your CA certificate, and a self-signed certificate may be used. For more information see Onboarding in the nRF Cloud documentation.

Whether using our APIs via CoAP or MQTT you will need to flash to your device:

1. The Amazon Root CA1 PEM file, which enables the device to authenticate the AWS IoT server.
2. The private key associated with the device certificate.

Additionally, if the device will be using MQTT, you will also need to flash the device certificate. For signing JWTs you will use the private key associated with the certificate. (During the device onboarding process we extract the corresponding public key from your uploaded certificate and use this for JWT signature verification.)

The second onboarding modality involves uploading a public key to verify the signatures of JSON Web Tokens (JWTs) sent by the device. Uploading a public key allows the device to use JSON Web Tokens (JWTs) signed by the private key of an asymmetric key pair, i.e., a private key that is different than the one used to sign the device's CSR (this key pair can be generated via the AT%KEYGEN command). If you are using JWTs signed by the device CSR key, and you have also uploaded the device's certificate via this or the OnboardDevices endpoint, there is no need to upload the public key, because it is automatically extracted from the certificate. This is useful for devices that only want to consume nRF Cloud services over REST.

Please note: Public keys must be ES256. For more information, see the nRF Cloud REST Authentication documentation.

This endpoint supports asynchronous bulk operations. Your data will be validated, and if valid, you will receive an HTTP 202 response with a bulkOpsRequestId. You can use this id with the bulk ops endpoints to track the request's processing status. If the bulk ops request indicates FAILED status, check the JSON errors file (URL in the bulk ops request details), fix the offending rows, then re-submit the CSV with only those rows.

Each CSV row must in the format deviceId,[subType],[tags],[supportedFirmwareTypes],"certificate",[onboardingToken], where:

Note: Each device must be onboarded with either a certificate OR an onboarding token, but not both. Within the same CSV file, you can have some devices onboarded with certificates and others with onboarding tokens.

Columns may appear in any order when a header row is present. If the header row is missing, the default column order is applied strictly: deviceId,subType,tags,supportedFirmwareTypes,certificate. To use the onboardingToken field, you must include a header row.

Examples of CSV rows:

All values set with certificate

deviceId,subType,tags,supportedFirmwareTypes,certificate,onboardingToken
f69c0e45-7f04-4949-8def-bb2215b4223e,my-thing-type,tag1|tag2,APP|MODEM,"-----BEGIN CERTIFICATE-----
MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
-----END CERTIFICATE-----
",

Using onboarding token instead of certificate

deviceId,subType,tags,supportedFirmwareTypes,certificate,onboardingToken
a1b2c3d4-5e6f-7890-abcd-ef1234567890,my-thing-type,tag1|tag2,APP|MODEM,,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

subType not set

deviceId,tags,supportedFirmwareTypes,certificate
f69c0e45-7f04-4949-8def-bb2215b4223e,tag1|tag2,APP|MODEM,"-----BEGIN CERTIFICATE-----
MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
-----END CERTIFICATE-----
"

subType and tags not set, but supported supportedFirmwareTypes are set

deviceId,supportedFirmwareTypes,certificate
f69c0e45-7f04-4949-8def-bb2215b4223e,APP|MODEM,"-----BEGIN CERTIFICATE-----
MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
-----END CERTIFICATE-----
"

Using the public key modality

• deviceId,supportedFirmwareTypes,certificate
  f69c0e45-7f04-4949-8def-bb2215b4223e,APP|MODEM,""-----BEGIN PUBLIC KEY-----
  MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
  -----END PUBLIC KEY-----
  "

Without header row (default strict column order: deviceId,subType,tags,supportedFirmwareTypes,certificate)

• f69c0e45-7f04-4949-8def-bb2215b4223e,,tag1|tag2,,"-----BEGIN CERTIFICATE-----
  MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
  -----END CERTIFICATE-----
  "
• Note: The onboardingToken field is not available when using the headerless format.

Also note:

• Max number of rows is 1000.
• Do not leave any blank lines.

Example of uploading CSV data as a binary file:

curl -X POST $API_HOST/v1/devices \
--data-binary @$PATH_TO_CSV_FILE \
-H "Content-Type: application/octet-stream" \
-H "Authorization: Bearer $API_KEY"

Note that for some unknown reason, curl will strip the final line break in each ES256 cert when sending the CSV file using a non-binary content-type, e.g., using syntax such as -d @$PATH_TO_CSV_FILE -H "Content-Type: text/csv". Therefore, with curl use --data-binary only. If you want to send the CSV as text, use a REST client like Postman or Insomnia. To synchronously provision a single device, you can also use the OnboardDevice endpoint.

Onboard and associate a single device with your nRF Cloud account.

This endpoint supports two onboarding modalities depending upon whether you include device certificates or a provisioning token in your payload.

Uploading a device certificate allows the device to use nRF Cloud services using any supported connectivity protocol, such as HTTP/REST, MQTT, and CoAP. This is the recommended method for onboarding devices. Unlike the CreateDeviceCertificate endpoint, this endpoint involves your own CA certificate and requires you to upload device certificates that you have already obtained, whether via a CSR produced by the AT%KEYGEN command (modem firmware v1.3+), or offline via your own script. We impose no rules on your CA certificate, and a self-signed certificate may be used. For more information see Onboarding in the nRF Cloud documentation.

For device type nrf93m, you should provide a provisioning token instead of a certificate.

Whether using our APIs via REST or MQTT you will need to flash to your device:

1. The Amazon Root CA1 PEM file, which enables the device to authenticate the AWS IoT server.
2. The private key associated with the device certificate.

Additionally, if the device will be using MQTT, you will also need to flash the device certificate. For signing JWTs you will use the private key associated with the certificate. (During the device onboarding process we extract the corresponding public key from your uploaded certificate and use this for JWT signature verification.)

For bulk onboarding of devices, please use the OnboardDevices endpoint.

Register one or more public keys so that the signatures for JSON Web Tokens (JWTs) sent by the device can be verified.

This endpoint supports the following use case:

• Devices that are onboarded on nRF Cloud and want to use a dedicated private key for signing JWTs instead of the key associated with the device's cloud-onboarding certificate (e.g., onboarded with the OnboardDevices endpoint, which automatically extracts and stores a public key during the onboarding process for use in subsequent JWT signature verifications).

Only one public key may be registered for each device. Uploading CSV data with a different key for the same device will overwrite the existing key.

Public keys must be ES256. For more information, see the nRF Cloud REST Authentication documentation.

This endpoint supports asynchronous bulk operations. Your data will be validated, and if valid, you will receive an HTTP 202 response with a bulkOpsRequestId. You can use this id with the bulk ops endpoints to track the request's processing status. If the bulk ops request indicates FAILED status, check the JSON errors file (URL in the bulk ops request details), fix the offending rows, then re-submit the CSV with only those rows.

Each CSV row must in the format deviceId,"keyPem", where:

Example of a CSV row:

All values set

f69c0e45-7f04-4949-8def-bb2215b4223e,"-----BEGIN PUBLIC KEY-----
MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
-----END PUBLIC KEY-----
"

Also note:

• Max number of rows is 1000.
• Do not use a header.
• Do not leave any blank lines.

Example of uploading CSV data as a binary file:

curl -X POST $API_HOST/v1/devices/public-keys \
--data-binary @$PATH_TO_CSV_FILE \
-H "Content-Type: application/octet-stream" \
-H "Authorization: Bearer $API_KEY"

Note that for some unknown reason, curl will strip the final line break in each ES256 public key when sending the CSV file using a non-binary content-type, e.g., using syntax such as -d @$PATH_TO_CSV_FILE -H "Content-Type: text/csv". Therefore, with curl use --data-binary only. If you want to send the CSV as text, use a REST client like Postman or Insomnia.

Register one or more device certificates. If a device has already been added to your team (onboarded) this will delete its existing cert and replace it with the new one. It is recommended to update existing devices with their new certificates before registering them here. If it is not onboarded, please use the OnboardDevice endpoint to complete the process which allows your device(s) to use nRF Cloud.

This endpoint supports asynchronous bulk operations. Your data will be validated, and if valid, you will receive an HTTP 202 response with a bulkOpsRequestId. You can use this id with the bulk ops endpoints to track the request's processing status. If the bulk ops request indicates FAILED status, check the JSON errors file (URL in the bulk ops request details), fix the offending rows, then re-submit the CSV with only those rows.

Each CSV row must in the format deviceId,"certPem", where:

Example of a CSV row:

All values set

f69c0e45-7f04-4949-8def-bb2215b4223e,"-----BEGIN CERTIFICATE-----
MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
-----END CERTIFICATE-----
"

Also note:

• Max number of rows is 1000.
• Do not use a header.
• Do not leave any blank lines.

Example of uploading CSV data as a binary file:

curl -X POST $API_HOST/v1/devices/certificates \
--data-binary @$PATH_TO_CSV_FILE \
-H "Content-Type: application/octet-stream" \
-H "Authorization: Bearer $API_KEY"

Note that for some unknown reason, curl will strip the final line break in each ES256 public key when sending the CSV file using a non-binary content-type, e.g., using syntax such as -d @$PATH_TO_CSV_FILE -H "Content-Type: text/csv". Therefore, with curl use --data-binary only. If you want to send the CSV as text, use a REST client like Postman or Insomnia.

Modify the device's state as stored in its shadow. You do not have to pass the entire shadow. You can update a specific portion by setting the correct JSON field path:

export DEVICE_VERSION=$(curl $API_HOST/v1/devices/$DEVICE_ID -H "Authorization: Bearer $API_KEY" | jq -r '.["$meta"].version')
curl -X PATCH $API_HOST/v1/devices/$DEVICE_ID/state -d '{ "reported": { "device": { "serviceInfo": { "fota_v1": ["BOOT"] } } } }' -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -H "If-Match: $DEVICE_VERSION"

Allows a user or IP device to send a message that is subsequently published over an MQTT topic, on behalf of the IP device whose deviceId is specified. The device ID for the message comes from the topic. For instance, if the topic property on the request is m/d/nrf-352656101081837/d2c/custom, the device ID determined for the message will be 'nrf-352656101081837'.

For dictionary based binary logs via the d2c/bin topic, the message must be base64 encoded. For instance, for the device nrf-352656101081837 the request body would be:

{
  "topic": "d/nrf-352656101081837/d2c/bin",
  "message": "blJGQwAAAAAd2qCkkAEAAAEAAABoZWxsbyB3b3JsZA=="
}

For more information, see Sending device messages.

Fetch historical device messages.

Currently supported parameter combinations:

appId + deviceId

topic + deviceId

appId

deviceId

topic

Not supported:

appId + topic

appId + topic + deviceId

For more information, see our nRF Cloud documentation on device messages.

Fetch device alerts. For more information, see our nRF Cloud documentation on device alerts.

Archives an Alert. For more information, see our nRF Cloud documentation on device alerts.

Restore an archived Alert. For more information, see our nRF Cloud documentation on device alerts.