Skip to content
IoT Service

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)