Overview of the nRF Cloud APIs

This section introduces the nRF Cloud REST, MQTT, and CoAP APIs.

The following diagram shows the general relationships between the APIs, services, devices, and other components:

nRF Cloud REST API

The nRF Cloud REST API is organized into the following categories:

• General endpoints related to account management, certificates, and tokens and keys.

• Device management endpoints for IP devices:

  • Device data.
  • Device onboarding.
  • Viewing device messages, including MQTT.
  • Message Routing Service.

• Endpoints related to updating firmware:

  • Creating, uploading, and managing bundles.
  • Initiating and managing update jobs.
  • Monitoring firmware update executions.

• Location Services endpoints:

  • GNSS assistance and prediction data.
  • Querying cell, ground fix and Wi-Fi location.
  • Viewing location history.
  • Determining a physical address based on location data.

• Endpoints to monitor bulk operation requests, such as bulk onboarding and secure provisioning.

• Endpoints related to nRF Cloud services:

  • Managing IMEIs.
  • Device identity.
  • Provisioning service.

Authentication

Authentication for REST depends on the operation and which components are communicating:

• User-to-device or user-to-nRF Cloud operations require an API key. These are mostly related to onboarding, fetching device data, and viewing team or usage information.
• Device-to-cloud (D2C) endpoints are authenticated using JSON Web Tokens (JWTs). Since these operations originate from devices, nRF Cloud requires a high level of security.
• Cloud-to-cloud (C2C) use cases, such as some integrations of Location Services through a proxy server, are authenticated with JWTs.

Access

C2C use of nRF Cloud requires a Pro or Enterprise plan.

See REST API authentication for more detail on authentication concepts, and generating tokens and keys for a guide.

nRF Cloud CoAP API

The nRF Cloud CoAP API provides an additional protocol option for devices that need to optimize network traffic and power consumption. It is compatible with the following nRF Cloud components and services:

• Location Services
• FOTA
• Messaging (See also the Message Routing Service in the nRF Cloud REST API)
• Device shadow management

See the CoAP overview for more information.

nRF Cloud MQTT API

Using the nRF Cloud MQTT API depends on which topics a device is allowed to use based on its IoT security policy. The MQTT API supports D2C use cases and some user-to-cloud operations, such as publishing messages directly on MQTT topics to which your devices are subscribed.

For example, you can use the MQTT API for secure MQTT communication over WebSockets in the nRF Cloud portal.

See the MQTT API overview for more on authenticating MQTT operations, as well as documentation of all available nRF Cloud MQTT topics.

Choosing a protocol

See Choosing a protocol for a comparison of nRF Cloud APIs, including example use cases.

API limits

API limits apply only to the free Developer plan. These limits apply to the entire team. They reset on the first day of the month.

If API operations in your team begin to fail, verify that you have not exceeded your plan limits from the Cost Control Center.

Once you reach your plan's limits for a service, REST API requests to that service return a 400 error with an nRFCode of 40005. These requests do not resolve.

Attempted requests over MQTT exceeding your plan limit do not return error messages. The messages are dropped, and the requests do not resolve.