Skip to main content

REST API

What is REST?#

REST stands for "representational state transfer". It's one of the most well-established ways to build and expose APIs for applications that communicate over the internet.

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.

The nRF Cloud REST API#

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.

Authentication#

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.

API Key (Simple Token)#

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.

JSON Web Tokens (JWT)#

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.

note

Devices using the REST API must also use modem firmware v1.3.x, which has its own hardware requirements as described in the release notes.

It is not possible to use the nRF Cloud FOTA service to upgrade to modem firmware v1.3.x from any previous version.

Signing (Private) and Verification (Public) Keys#

JWTs must be signed by the private key of an ES256 asymmetric key pair. The only JWT algorithm we support is ES256*.

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

JWT Payloads#

The payload for each JWT depends on the type of key used:

Signing (Private) KeyPayload
Device KeyThe sub claim must contain the device ID. If your device is using its internal UUID as the device ID and modem_jwt_generate, the sub claim can be omitted. Do not include the aud claim.
Service KeyThe aud claim must contain your Team ID. The sub claim may contain a device ID if the request is servicing a single device (not typical).

Creating JWTs#

The most secure way to use JWTs from devices is with the Modem JWT library or using the AT%JWT command directly. This requires modem firmware v1.3.x or later.

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 AT%JWT command.

Using JWTs in Requests#

Add the JWT to your Authorization header as a Bearer token. Here is a cURL example:

-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VJZGVudGlmaWVyIjoiZmIwOWNkZmItZTY4Yy00NGUzLWIwMTQtMmJlZDc4Yzk3OTQ5In0.RUAWePWjqRn4TK6EXsiKrsMM69FqDjg7dn52hrqG8CM"

Additional Resources#

These practical "how to" guides will help you take the next steps:

REST Client Tools#

We encourage you to try our REST API with a good REST client tool such as Insomnia or Postman.

Of course, you can always use cURL or other utilities from the command line.

Use of If-Match Headers#

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 PreconditionFailedError.