This section introduces the nRF Cloud REST API.
If you are not familiar with REST APIs, start with the Postman Learning Center.
The nRF Cloud REST API
- In any web browser, open and download https://api.nrfcloud.com/v1/openapi.json.
- In any REST tool, GET https://api.nrfcloud.com/v1/openapi.json.
- At the top of the API reference introduction page, click the Download button.
REST tools, such as Postman or Insomnia, can parse the downloaded file and create a collection of endpoints for you.
See also Using the REST API.
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 FetchCurrentPendingFOTAJobExecution, support both schemes.
API key (simple token)
Most requests to the REST API require a simple authentication token (API key) in the
Authorization header. Here is a cURL example of this header:
-H "Authorization: Bearer d8be845e816e45d4a9529a6cfcd459c88e3c22b5"
You can retrieve and manage API keys through your User Account page on the nRF Cloud portal. Previously issued API keys are valid for up to 60 minutes.
JSON Web Token
REST endpoints intended for devices or proxy servers require a JWT. If you are not familiar with JWTs, learn more and create a JWT to use when calling the nRF Cloud REST API at jwt.io, which also provides an Introduction to JWTs.
You cannot update to modem firmware v1.3.x from any previous version using the nRF Cloud firmware over-the-air (FOTA) service.
Signing (private) and verification (public) keys
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 for each device.
- Service key: generated by nRF Cloud and unique for each service, such as Location Services or the FOTA service. This is typically only used for proxy servers. Use of service keys requires a Pro or Enterprise plan.
nRF Cloud obtains public keys in one of the following ways:
- Upload the key manually with the
- nRF Cloud automatically extracts the device key from the device's non-JITP certificate during the provisioning process.
- nRF Cloud automatically extracts the device key from the device's JITP certificate, if applicable and no other public key can be found to verify the signature.
- Upload the key manually with the
Service key: nRF Cloud generates and stores the service key on demand through the Service Management interface. This requires a commercial plan. Contact Nordic Semiconductor Sales for more information.
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 UUID in the payload's
iss claim. This is useful if your device uses its UUID as its device ID, in which case, you can omit the
If your device uses a different value for the device ID, you must provide that value as the
subject claim of the JWT. For example, if you want to use JWTs on Nordic Semiconductor products that have a device ID formatted as
nrf-[IMEI], as is the case for the nRF9160 DK and Thingy:91, you must either provision 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
Using JWTs in requests
Add the JWT to the
Authorization header as a
Bearer token. Here is a cURL example:
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VJZGVudGlmaWVyIjoiZmIwOWNkZmItZTY4Yy00NGUzLWIwMTQtMmJlZDc4Yzk3OTQ5In0.RUAWePWjqRn4TK6EXsiKrsMM69FqDjg7dn52hrqG8CM"
REST client tools
Use cURL or other utilities to call APIs from the command line.
API endpoints that change existing resources, such as
UpdateDeviceName, allow you to include an optional
If-Match header to avoid lost updates.
The value for this header is taken from the
$meta.version property. The value is also available in the
ETag for endpoints that return a single resource, for example,
If the version you pass is not equal to the latest version of the resource, you get an
HTTP 412 and
See the following guides for next steps: