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.

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.

Client private key generation¶

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

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

Certificate Signing Request (CSR)¶

The device generates a new key pair and return a certificate signing request (CSR). Specify the secTag, 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 secTag 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 secTag parameter as explained in the %CMNG command description.

{
  "request": {
    "clientCertificate": {
       "secTag": 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 secTag and password parameters as explained in the %CMNG command description.

{
  "request": {
    "clientPrivateKey": {
       "secTag": 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 secTag parameter, as explained in the %CMNG command description.

{
  "request": {
    "preSharedKey": {
       "secTag": 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"

Device status during the secure provisioning process¶

A claimed device may have one of the following statuses:

READY: The device has been claimed and is ready to be provisioned.
PROVISIONING: The device has connected to the Provisioning Service and the provisioning process is in progress. You can monitor the status of the individual commands.
AWAITING: The device has already received all commands defined in its provisioning configuration, but the provisioning process is not yet finished. Add more commands to the configuration, along with the finished command.
PROVISIONED: The device has received all commands successfully and acknowledged the last finished command.
ERROR: The device has responded with an error to a provisioning command. The provisioning process is suspended at this point and requires the user to intervene manually.
BLOCKED: The device is blocked and will not receive any new provisioning commands. Unblock it first if you want it to be provisioned.

See next¶

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