Create an Operational Certificate
The following request creates an operational certificate for the device and activates a device in IoT, if you have not activated it yet. This call uses a customized authentication.
####API Request
POST {BaseURL}/certificates
####Customized JWT authentication
Before you start calling the Create an Operational Certificate API, review the following guidelines:
- JWT is signed using the private key (HSM key) of a device using the ES256 or RS256 algorithm.
- A signed JWT is passed in the request JSON body as mentioned in the REQUEST section.
- The fields described in the following table are required in the JWT payload context when creating a JWT token.
- Refer to the Sample Code section.
| Parameter | Data Type | Description |
|---|---|---|
| manufacturer* | string | manufacturer of a device |
| model* | string | make model of a device. |
| serialNumber* | string | serial number of the device. |
| expiry* | int | expiry of JWT in UNIX epoch timestamp format. |
| csr | string | (optional) CSR value. |
| connectionContext | string | (optional) Unique context of device connection. When a physical device contains multiple devices, this parameter should be configured uniquely for each device. Please refer Device Connections how to for more info . |
A device MUST declare an expiry e such that time.now() < e < (time.now() + 60m). In other words, the expiry in JWT token can be set to any epoch within next 60 minutes.
###Request
####Request Body application/json
| Parameter | Data Type | Description |
|---|---|---|
| token* | string | Signed JWT token for claims: Manufacturer, Model , serial number, expiry & CSR (optional). |
####Response
Status Code 200: When a device certificate creation and activation of IOT is successfully done.
####Response Model application/json
| Parameter | Data Type | Description |
|---|---|---|
| deviceId* | string | Identifier of the device. |
| groupId* | string | Group Id of the device created in IOT system. |
| certificate* | string | Operational certificate for the device. |
| clientId* | string | Client Id required for MQTT connection. |
| username | string | Username required for MQTT connection - only for devices connecting Azure IoT gateway. |
Status Code 400: When an invalid request for creation is sent
Status Code 401: When the calling identity is not authorized to create the device certificate
For more details, refer to API documentation.
####Sample code to generate a JWT token using Python
import jwt import time seconds = time.time()+1800 encoded = jwt.encode({ "manufacturer": "Trimble", "model": "group26891", "serialNumber": "Device78903", "expiry": seconds }, b'-----BEGIN EC PRIVATE KEY-----\nMIGkAgEBBDBeD5/0VGtdp2gEGM9QAjT05pwMvip5UJZXCcDTs0FIr0cJCaFFj7/G\nOw3voClGBXegBwYFK4EEACKhZANiAASBX+DjjFvGFyMsv+MWKzHRUXR74I0sToIy\n8Inu6G+QIRKi2gKdHFkspehd9rHZxCvcCXzxYX2nM7amu7ooDDLX6mqdyznXcj2/\n3k1awUGPTLuW8LXGXj54XIhJZE0NpII=\n-----END EC PRIVATE KEY-----', algorithm="ES256") print(encoded)