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