Skip to content

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. Expand the sections below for more information about each command type and an example message body for each request type.

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 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 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 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 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 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 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",
       ...
    }
  }
}

Finished

Add the finished command without any parameters at the end of the provisioning configuration. This command informs the provisioning client that the process has finished. The device can then begin operating according to its use case. When the service processes this command, the device status is set to PROVISIONED.

When all commands has been processed successfully but there is no finished command added to the provisioning configuration, the device status is set to AWAITING. This can happen if the final command is to generate a CSR. You must sign the device certificate and add it as a new Client certificate, as well as add the finished command to the provisioning configuration:

{
  "request": {
    "finished": {
    }
  }
}

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.