Provisioning configuration through the APIs

This guide explains how to define the provisioning configuration of your claimed devices using the REST API. See more about provisioning configuration.

Access

The Provisioning Service is available to editor, admin, and owner roles. Some operations are also available to viewers. See the API documentation for more information.

Adding commands to the device's provisioning configuration

This section describes the commands that are available when a device is claimed for secure provisioning. For more details about managing the provisioning configuration and parameter formatting, see the Device provisioning API documentation.

You can add up to 20 commands for a single claimed device.

The following sections demonstrate the different command types available through the CreateDeviceProvisioningCommand endpoint.

Click to expand the sections below for more information about each command type and an example message body for each.

Cloud access key generation

Requests the device to generate a key pair and registers the public key with nRF Cloud. The device can use its private key to sign JWTs to access nRF Cloud services. This command also exports a CSR for creating a device certificate for use on nRF Cloud. The cloud access key command is included in auto-onboarding.

{
  "request": {
    "cloudAccessKeyGeneration": {
      "secTag": 16842753
    }
  }
}

Client private key generation

The device generates a new key pair and returns the public key. Specify the sec_tag parameter as explained in the %KEYGEN AT command description.

{
  "request": {
    "clientPrivateKeyGeneration": {
      "secTag": 16852753
    }
  }
}

Certificate Signing Request (CSR)

The device generates a new key pair and returns a certificate signing request (CSR). Specify the sec_tag, attributes, and keyUsage parameters as explained in the %KEYGEN AT command description.

{
  "request": {
    "certificateSigningRequest": {
      "secTag": 16852753,
      "attributes": "O=Nordic Semiconductor,L=Trondheim,C=no,CN=0123456789",
      "keyUsage": "101010000"
    }
  }
}

Server certificate

This command injects a new server certificate (root CA) to the device. The certificate must be given in PEM format. Specify the sec_tag parameter as explained in the %CMNG AT command description.

{
  "request": {
    "serverCertificate": {
      "secTag": 16852753,
      "content": "-----BEGIN CERTIFICATE-----\nMIIDSjCCA...bKbYK7p2CNTUQ\n-----END CERTIFICATE-----"
    }
  }
}

Client certificate

This command injects a new client certificate to the device. The certificate must be given in PEM format. Specify the sec_tag parameter as explained in the %CMNG AT command description.

{
  "request": {
    "clientCertificate": {
      "sec_tag": 16852753,
      "content": "-----BEGIN CERTIFICATE-----\nMIIDSjCCA...bKbYK7p2CNTUQ\n-----END CERTIFICATE-----"
    }
  }
}

Client private key

This command injects a new private key to the device. The key must be given in encrypted PEM format. Specify the sec_tag and password parameters as explained in the %CMNG AT command description.

{
  "request": {
    "clientPrivateKey": {
      "sec_tag": 16852753,
      "content": "-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIICz...ukBu\n-----END ENCRYPTED PRIVATE KEY-----",
      "password": "abcdefg"
    }
  }
}

Pre-shared Key (PSK)

This command injects a new PSK to the device. Specify the PSK identity and secret, as well as the sec_tag parameter, as explained in the %CMNG AT command description.

{
  "request": {
    "preSharedKey": {
      "sec_tag": 16852753,
      "identity": "psk_id",
      "secret": "1946017E17C20001FF5F160021480119"
    }
  }
}

Configuration

You can send a configuration to the provisioning client itself. The config properties are specific to the provisioning client you are using. The following example is for demonstration purposes only and is not specific to the client Nordic Semiconductor provides:

{
  "request": {
    "config": {
       "cloud.url": "mqtt://xxx.nrfcloud.com",
       "provisioning.interval-sec": "3600",
       ...
    }
  }
}

Monitoring provisioning progress

List your claimed devices with a certain status, for example:

curl -X GET $API_HOST/v1/claimed-devices?status=PROVISIONED -H "Authorization: Bearer $API_KEY"

See next

For more information on recovering from errors, as well as resetting and skipping commands, see Troubleshooting.