If you are new to the concept of REST APIs—as is the case with many hardware and firmware engineers—you can easily find tutorials on the Web to get you jump started. A good place to start is the Postman Learning Center.nRF Cloud's REST API is built on the OpenAPI 3.x specification. It exposes many different endpoints that you and your devices can invoke in order to do something, get something, etc. For some examples, see the "Using the REST API" guides.
The REST API authenticates users with an API key (Simple Token), and devices with a JSON Web Token (JWT). Only a subset of the nRF Cloud REST API endpoints should be called by devices instead of users. These endpoints indicate "JSON Web Token" in the "Authorizations" section. Otherwise, "Simple Token" is indicated.
Some endpoints, like the FetchCurrentPendingFOTAJobExecution endpoint, even support both schemes.
Most requests to the REST API require a simple authentication token, i.e., your API key, in the
Authorization header. Here is a cURL example of this header:
-H "Authorization: Bearer d8be845e816e45d4a9529a6cfcd459c88e3c22b5"
API keys can be retrieved and managed in your Account page on nRFCloud.com. Note that previously issued API keys remain valid for up to 60 minutes.
A subset of the REST endpoints—specifically, those intended for use by devices or proxy servers—require the use of a JSON Web Token (JWT). It is beyond the scope of this document to provide an introduction to JWTs in general. If you are not familiar with them, a great place to learn more—and even to create a JWT to use when calling the nRF Cloud REST API—is jwt.io, which also provides an Introduction to JWTs.
When a JWT is received by an nRF Cloud endpoint, its digital signature must be verified by the corresponding public key.
nRF Cloud supports two types of private keys:
- Device Key: generated on the device and unique per device.
- Service Key: generated by nRF Cloud and unique per service (e.g., each type of Location Services or the FOTA Service). This is typically only used for proxy servers. Use of service keys requires a special business agreement with Nordic Semiconductor.
nRF Cloud obtains the public keys in one of the following ways:
- Device Key:
- Uploading it via the RegisterPublicKeys endpoint.
- nRF Cloud automatically extracting it from the device's non-JITP certificate during the ProvisionDevices endpoint provisioning process.
- nRF Cloud automatically extracting it from the device's JITP certificate (if applicable, and no other public key can be found to verify the signature).
- Service Key:
- nRF Cloud generates and stores it on demand via the Service Management UI (if enabled: again, this requires a special business agreement with Nordic Semiconductor).
* nRF9160 DK and Thingy:91 devices are shipped with RSA256 certificates, which are not supported for JWT signing by modem firmware v1.3.x and later. To use JWTs with these devices, delete the device from nRF Cloud and re-provision it with a new ES256 device certificate.
The payload for each JWT depends on the type of key used:
|Signing (Private) Key||Payload|
|Device Key||The |
|Service Key||The |
JWTs generated by the modem automatically contain the device's UUID in the payload's
iss claim. This is useful if your device uses its UUID as its device id. In that case, the
subject can be omitted.
However, if your device uses a different value for the device id then you must provide it as the
subject claim of the JWT. For example, if you want to use JWTs on Nordic products that have a device ID formatted as
nrf-[IMEI] (which is the case for nRF9160 DK and Thingy:91 products), you will either need to flash a new certificate that uses the UUID (and re-provision the device on nRF Cloud), or pass the
nrf-[IMEI] id as the
subject to the
Add the JWT to your
Authorization header as a
Bearer token. Here is a cURL example:
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VJZGVudGlmaWVyIjoiZmIwOWNkZmItZTY4Yy00NGUzLWIwMTQtMmJlZDc4Yzk3OTQ5In0.RUAWePWjqRn4TK6EXsiKrsMM69FqDjg7dn52hrqG8CM"
These practical "how to" guides will help you take the next steps:
Of course, you can always use cURL or other utilities from the command line.
API endpoints that change existing resources, such as the UpdateDeviceName endpoint, allow you to include an optional `If-Match` header to avoid the Lost Update Problem. The value for this header is taken from the `$meta.version` property (it's also available in the `ETag` for endpoints that return a single resource, e.g., FetchDevice. If the version you pass is not equal to the latest version of the resource, you will get an
HTTP 412 and