Skip to content

JWT authentication for nRF Cloud

This guide demonstrates how to authenticate requests to the nRF Cloud REST API using JSON Web Tokens (JWTs). For references and concepts, see the JWT section of the REST API authentication documentation.

If you want to generate a JWT and service key for Location Services with a proxy server, see Managing tokens and keys.


This guide is not a tutorial, and does not model real-world use cases with specific hardware. Instead, this guide provides a conceptual understanding of JWT authentication on nRF Cloud using tokens that you generate using an online tool.


You need the following for this guide:

Key extraction from a device certificate

For JWTs involving a device that is onboarded to nRF Cloud, the public key is extracted from the certificate and stored to nRF Cloud to verify the signatures of JWTs signed by the certificate's private key.

To extract the public key:

  1. Use the scripts in the nRF Cloud Utils project to create a CA certificate and a device certificate. These steps use NodeJS scripts, but the Utils project also provides Python scripts. If you do not want to use the scripts directly, you can use OpenSSL commands with a few modifications:

    export DEVICE_ID=<Device_ID>
  2. Use a subject and organizational unit (ou) of your choice:

    node dist/create-ca-cert.js --cnSubjectPrefix '/C=NO/ST=Norway/L=Trondheim/O=Nordic Semiconductor' --ou 'Test Devices'
  3. Create the device certificate using the CA certificate:

    node dist/create-device-cert.js --deviceId $DEVICE_ID


    If you are using an nRF9160 DK, inject the certificate to the device.

  4. Following the documentation for the ProvisionDevices endpoint, create a CSV file that contains the certificate that you just created. This is the PEM-formatted string in the *.crt.pem file.

  5. Call the ProvisionDevices endpoint to upload the CSV data. The following example shows CSV data encoded as a base64 string:

    export API_KEY=<your API key>
    curl --request POST \
    --url \
      --header 'Authorization: Bearer $API_KEY' \
      --header 'content-type: text/csv' \
  6. This returns a bulkOpsRequestId that you can use to check the status of the bulk operations request using the FetchBulkOpsRequest endpoint:

    curl --request GET \
      --header 'Authorization: Bearer $API_KEY'
  7. Create a JWT using the private key of the device certificate. To do this without writing code, go to

    If you have an nRF9160 DK, you can create a JWT using the %JWT AT command.


    Using AT commands can depend on the application or sample you are using. See the application or sample README for more information on using AT commands.

  8. The cryptographic algorithm for JWT signing defaults to HS256. Select ES256 from the Algorithm menu: algorithm selection

  9. Edit the payload for the device key:

       "sub": "f69c0e45-7f04-4949-8def-bb2215b4223e"


    The modem library uses iss if sub is not passed to the AT%JWT command. If you want to use iss, you must also add a hardware type such as nrf9160. to the start of the device ID. For example:

       "iss": "nrf9160.f69c0e45-7f04-4949-8def-bb2215b4223e"
  10. Copy the contents of your *.key.pem file and paste it to the lower right field of the Verify Signature pane:

    Setting the private key in

  11. The text in the left pane changes to the JWT encoded as a base64 string. You can now present this token when calling an nRF Cloud REST API endpoint that accepts JWTs, allowing the API to authenticate the request.


    The Invalid Signature warning appears because the public key in the right pane is the default key for the sample. It is not the public key corresponding to your private key, and therefore signature verification fails.


    This example uses the files generated for the device ID in the previous steps:

    openssl x509 -pubkey -noout -in ./certs/$DEVICE_ID.crt.pem > ./certs/$DEVICE_ID.public-key.pem

    This results in:

    -----BEGIN PUBLIC KEY-----
    -----END PUBLIC KEY-----


    The blank line below the text is part of the PEM format and must be kept.

  12. Paste this information into to verify the token's signature:

    Verifying the signature in

  13. Use the JWT you have created to authenticate a request to an nRF Cloud endpoint that requires JWTs. This example calls the GetAssistanceData endpoint using the JWT:

    curl --request GET \
    --url '' \
    --header 'Accept: application/octet-stream' \
    --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmNjljMGU0NS03ZjA0LTQ5NDktOGRlZi1iYjIyMTViNDIyM2UifQ.VRXRvIAxrdNml4zzUHboaE3oSFbjtUwAEa8QN2DuWrTsIUVVlmZFapY93w-ocwS5SpEdXFP8twMB3T8xTunGsQ' \
    --header 'range: bytes=0-500'

The expected response is in binary format with an HTTP 206 status code. This indicates that your request was authenticated. An HTTP status code of 401 indicates an authorization failure. See more on HTTP error codes.

Public key registration

The previous example signed JWTs using the private key associated with the device certificate, and verified the JWT signatures with the corresponding public key extracted from the certificate during the nRF Cloud onboarding process.

Your implementation might require that your device is provisioned on another IoT platform but still needs to call JWT-authenticated endpoints, for example, nRF Cloud Location Services. In this case, register the public key of each device's asymmetric key pair with nRF Cloud:

  1. Create a key pair using OpenSSL:

    openssl ecparam -out private-key.pem -name prime256v1 -genkey
    openssl ec -in private-key.pem -outform PEM -pubout -out public-key.pem

    You should now have two files containing the private and public keys of an asymmetric key pair in PEM format:

     # private-key.pem
    -----END EC PARAMETERS-----
    -----BEGIN EC PRIVATE KEY-----
    -----END EC PRIVATE KEY-----
    # public-key.pem
    -----BEGIN PUBLIC KEY-----
    -----END PUBLIC KEY-----


    In a real-world use case, key generation is handled by the nRF9160 modem through the %KEYGEN AT command.

    The blank line below the text in each file is part of the PEM format and should be retained.

  2. Create a CSV file that contains the public key that you just created, according to the RegisterPublicKeys endpoint reference.

  3. Call the RegisterPublicKeys endpoint to upload the data:

    curl --request POST \
      --url \
      --header 'Authorization: Bearer $API_KEY' \
      --header 'content-type: text/csv' \

    See the previous example regarding use of the bulkOpsRequestId.

  4. Repeat the previous steps for, using the private and public keys from this example to create a JWT.

  5. Use the JWT to authenticate a request to any nRF Cloud endpoint that specifies JSON Web Token in its Authorizations section.

Next steps

For real-world use of JWTs from actual devices, see Securely generating credentials for nRF91 Series devices.