Introduction to the REST API

This section introduces the nRF Cloud REST APIs. If you are not familiar with REST APIs, start with the Postman Learning Center.

See the API overview for a full list of API references.

The nRF Cloud REST API

The nRF Cloud REST API references are built on the OpenAPI 3.x specification. You can get the current schema as a JSON file in one of the following ways:

• In any web browser, open and download https://api.nrfcloud.com/v1/openapi.json.
• In any REST tool, call 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.

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.

Authentication

The REST API authenticates users with an API key, 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.

Tokens and keys

Authenticating requests to nRF Cloud involves tokens and keys.

A token is used to authenticate a request to the nRF Cloud APIs:

• An API key.
• A JWT.

A key refers to a public or private key used to sign a JWT. See more on generating tokens and keys.

API key

Some requests, usually those that come from a user and not a device, require a simple authentication token in the Authorization header. Here is a cURL example of this header:

-H "Authorization: Bearer d8be845e816e45d4a9529a6cfcd459c88e3c22b5"

note

API keys function as tokens, not keys. In some API references, an API key is referred to as a simple token.

See how to generate and retrieve API keys in the nRF Cloud portal. API keys are specific not only to the user, but the team. Your API key is different for each team.

This token is used for endpoints and operations other than Location Services and FOTA, and does not need to be signed with a key. The API key is also used to authorize requests based on user role.

JWT

REST endpoints intended for devices or proxy servers require a JSON Web Token (JWT). A JWT authenticates a request to a service from a device, so nRF Cloud can verify that it is from that device.

JWT payloads

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

Signing (private) key	Payload
Device key	The sub claim must contain the device ID. If your device is using its internal UUID as the device ID and modem_jwt_generate, omit the sub claim. Do not include the aud claim.

Creating JWTs

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

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 subject claim.

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 inject a new certificate that uses the UUID (and re-onboard the device to nRF Cloud), or pass the nrf-[IMEI] ID as the subject to the AT%JWT command.

Using JWTs in requests

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

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

Signing (private) and verification (public) keys

JWTs must be signed by the private key of an ES256 asymmetric key pair. It is the only JWT algorithm supported by nRF Cloud.

note

The nRF9160 DK and Thingy:91 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-onboard it with a new ES256 device certificate.

When a JWT is received by an nRF Cloud endpoint, its digital signature must be verified by the corresponding public key. The device key is generated on the device and is unique for each device.

nRF Cloud obtains the device's public key in one of the following ways:

• Upload the key manually with the RegisterPublicKeys endpoint.
• nRF Cloud automatically extracts the device key from the device's certificate during the onboarding 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.

For cloud-to-cloud Location Services authentication with a proxy server, use an Organization Auth Token (OAT) instead of a JWT. See the Location Services Quickstart for setup instructions.

REST client tools

You can call the REST API with a REST client tool such as Insomnia or Postman.

Use cURL or other utilities to call APIs from the command line.

If-match headers

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, FetchDevice.

If the version you pass is not equal to the latest version of the resource, you get an HTTP 412 and PreconditionFailedError.

Additional resources

See the following guides for next steps:

• JWT authentication on nRF Cloud.
• Getting started with your devices.
• Managing tokens and keys.
• Transforming JSON responses.