Edge JSON-RPC API for protocol translators

Note: This document describes the API version 1.

This document defines the JSON-RPC APIs that Edge Core supports and APIs that the Edge protocol translators expect. The Edge protocol translator implementations must adhere to this specification. The connection between Edge Core and a protocol translator is a WebSocket connection over a Unix domain socket.

• The API request payload is JSONRPC 2.0 messages.
• The default domain socket path is /tmp/edge.sock.
• The URI for the API version 1 is /1/pt.

Edge Core does not support persistent data storage. Therefore, when Edge Core shuts down, the state and all the data related to protocol translators and LwM2M Object structures are lost.

Websocket connection

The protocol translators and Edge Core use a WebSocket connection to exchange messages. You can find more information in the WebSocket RFC and specification.

• Edge Core provides only a Unix domain socket where the protocol translator implementations connect.
• Edge Core uses a WebSocket server and libwebsockets library.

Connection handling

Closing the WebSocket disconnects the protocol translator from Edge Core, and the other way around.

When the protocol translator closes the WebSocket connection, Edge Core cleans all associated data from its internal structures.

When Edge Core shuts down, it closes the WebSocket connections to the protocol translators and cleans all the associated data from its internal structures. When Edge Core turns on again, the protocol translators can reconnect.

Note: When reconnecting, the protocol translator must register itself and the devices again.

JSON-RPC 2.0 usage

See the JSON-RPC 2.0 specification.

• All requests must contain the id member.
• The id member can be a number or string. The id value is used to match a request to its response so it should be unique within the scope of a protocol translator connection. Other connected protocol translators can use the same value for the request id, and it does not cause requests to clash.
• The Edge Core protocol translator JSON-RPC API assumes that all parameters to JSON-RPC 2.0 methods are given in the params member of the Object.
• The method member must contain the function name. The value is restricted to ASCII characters.
• The jsonrpc member must contain the value 2.0.

JSON-RPC methods

Available methods in Edge Core:

• Protocol Translator Register.
• Device Register.
• Device deregister.
• Write.
• Certificate renewal list set.
• Renew certificate.
• Crypto get certificate.
• Crypto get public key.
• Crypto generate random.
• Crypto asymmetric sign.
• Crypto asymmetric verify.
• Crypto ECDH key agreement.
• Certificate enrollment.

Methods which should be implemented in the protocol translator:

• Write.
• Certificate renewal result

Object definitions

Object `device`

• Type: object
• Description: An Object describing an endpoint device. The device Object describes the endpoint device and its LwM2M Object structure containing Objects, Object instances and Resources.

Member deviceId (required)

• Type: string
• Description: The device ID. This value must be unique and reproducible for the endpoint device. The protocol translator must generate the same device ID for the same physical device every time it connects. This ensures that the endpoint device has the same identity in Device Management.

Member objects (optional)

• Type: array
• Description: The Object list for the device of the LwM2M Objects.

Object `lwm2m-object`

• Type: object
• Description: An Object describing an LwM2M Object. The LwM2M Object structure contains an Object ID and LwM2M Object Instances.

Member objectId (required)

• Type: integer
• Description: The Object ID. The LwM2M or IPSO Object ID describes LwM2M Object characteristics.

Member objectInstances (optional)

• Type: array
• Description: The Object Instance list for LwM2M Object Instances.

Object `lwm2m-object-instance`

• Type: object
• Description: An Object Instance describing an LwM2M Object Instance, the instance ID and list of Resources.

Member objectInstanceId (required)

• Type: integer
• Description: The Object Instance ID.

Member resources (optional)

• Type: array
• Description: The Resource list for the LwM2M Object Instance.

Object `lwm2m-resource`

• Type: object
• Description: A Resource Object describing the Resource characteristics. This Object describes the LwM2M or IPSO Resource.

Member resourceId (required)

• Type: integer
• Description: The LwM2M resource or IPSO resource ID.

Member operations (required)

Type: integer Description: The bit-field for allowed operations. The allowed Resource operations, or any combination of them, are:

read   : 0x01
write  : 0x02
execute: 0x04
delete : 0x08

The bit-field is used to contain the operation or combinations of operations. For example, to allow read and execute operations when registering a Resource, the field value is 0x05.

The value can be constructed with a logical OR operation: 0x01 | 0x04 = 0x05.

The set operations in the bit-field can be checked with logical AND operations:

• 0x05 & 0x01 = 0x01 equals the read operation.
• 0x05 & 0x02 = 0x00 indicates that the write operation is not set.

Member type (required)

• Type: string
• Description: The LwM2M Resource value type. Please refer to LwM2M specification for the value types.
• Allowed values:
  • string
  • int
  • float
  • bool
  • opaque
  • time

Member value (required)

• Type: string
• Description: The value as a Base64-encoded string. All values must be passed as Base64-encoded values. This is required for binary content support. Refer to the LwM2M specification for encoding of the value types.

Object `write`

• Type: object
• Description: The write operation data container. This object describes which resource is the target of the operation defined in the uri member. The operation member defines the initiated operation, and the value member contains the value for the write operation or arguments for the execute operation.

Member operation (required)

• Type: integer
• Description: The operation to execute.

  read   : 0x01
  write  : 0x02
  execute: 0x04
  delete : 0x08
  

The bit-field is used to contain the operation or combinations of the operations.

When the write function is targeted to a Resource, it must contain only one operation.

The set operations in the bit-field can be checked with logical AND operations:

• 0x04 & 0x04 = 0x04 equals the execute operation.
• 0x02 & 0x04 = 0x00 indicates that the write operation is not set.

Member uri (required)

• Type: object
• Description: The URI to LwM2M Resource. The URI LwM2M Resource contains the device ID, Object ID, Object Instance ID and the Resource ID.

Member value

• Type: string
• Description: The value as a Base64-encoded string. The encoded value can contain a string, an integer, float, boolean, opaque, time or object link value.
• Required for operation write 0x02.
• Optional for operation execute 0x04.

Refer to the OMA Lightweight Machine to Machine Technical Specification for data type specifications of value types.

Generic error codes

You can receive the following error responses if any of the callable methods fail:

Available methods from Edge Core

Protocol Translator Register (method: `protocol_translator_register`)

All protocol translators must register before sending any other JSON-RPC messages.

The registration creates an LwM2M (object ID 26241) Object Instance in Edge Core. The Object with ID 26241 is used to store information about the protocol translators. When a new protocol translator is registered, an Object Instance is created under the Object. Each new protocol translator is represented as an Object Instance under Edge Core's Object. The Object Instance contains two Resources:

• 0, the name of the protocol translator. The value is a string.
• 1, the number of the connected endpoints. The value is an integer.

Edge Core
* Object(26241)
   * Object Instance (0) <-- 1st protocol translator
      * Resource (0) <-- Protocol translator name
      * Resource (1) <--  Number of endpoints
   * Object Instance (1) <-- 2nd protocol translator
      * Resource (0) <-- Protocol translator name
      * Resource (1) <--  Number of endpoints

Parameter name (required)

• Type: string
• Description: Protocol translator name. The name must be unique across connected protocol translators to a given Edge Core instance.

Result

A successful registration of the protocol translator returns an ok response.

Errors

A failed registration of the protocol translator returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "protocol_translator_register",
  "params": {
    "name": "pt-example"
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Value for key `name` missing or empty",
    "message": "Invalid params"
  }
}

Device Register (method: `device_register`)

You must register all endpoint devices individually with this method to Edge Core. Edge Core handles endpoint registration to Device Management. The endpoint device inherits the lifetime of Edge Core. Edge Core must deliver the endpoint device lifetime to Device Management.

Edge Core records the passed LwM2M Object structure and sends it to Device Management. The protocol translator receives an ok response when the endpoint device registration to Edge Core is successful. There is no notification of successful registration to Device Management; Edge Core must handle and register the endpoint devices.

If Edge Core receives an incorrect device registration message, the LwM2M Object structure and endpoint device data is not registered to Edge Core and Device Management.

Note: The protocol translator must be registered to Edge Core before registering devices.

Parameter device (required)

• Type: object
• Description: The device Object containing the endpoint device LwM2M Object and Resources.

Result

A successful device registration returns an ok response.

Errors

A failed device registration returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "device_register",
  "params": {
    "deviceId": "device-id-1",
    "objects": [{
      "objectId": 3306,
      "objectInstances": [{
        "objectInstanceId": 0,
        "resources": [{
          "resourceId": 5700,
          "operations": 3,
          "type": "float",
          "value": "P4aNuQ=="
        }]
      }]
    }]
  }
}

Tip: The operations key is bit-coded, and the value 0x01 | 0x02 = 0x03 indicates that the read and write operations are allowed.

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing or invalid 'deviceId' field.",
    "message": "Error"
  }
}

Device deregister (method: `device_unregister`)

With this method, the protocol translator can deregister an endpoint device from Edge Core. The corresponding endpoint and LwM2M object structure are removed from Edge Core.

The device deregistration is not propagated to Device Management. Endpoint device registration and deregistration rely on the lifetime of Edge Core.

Note: You must register the protocol translator to Edge Core before deregistering devices and register the device to Edge Core before initiating deregister.

Parameter deviceId (required)

• Type: string
• Description: The device ID to deregister.

Result

A successful device deregistration returns an ok response.

Errors

A failed device deregistration returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "device_unregister",
  "params": {
    "deviceId": "device-id-1"
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing or invalid 'deviceId' field.",
    "message": "Error"
  }
}

Write (method: `write`)

You can update the endpoint device Resources by using the write method.

If Edge Core replies ok, it records the value. The value is then available for querying in Device Management and notifications. If Edge Core responds with an error, it does not record the value. Edge Core must forward the value to Device Management.

Note: The value, regardless of the LwM2M type, must be Base64-encoded. This is required to support binary content.

The value formats allowed for write operations are defined as:

• string: UTF-8.
• integer: A binary signed integer in network byte-order (8, 16, 32 or 64 bits).
• float: IEEE 754-2008 floating point value in network byte-order (32 or 64 bits).
• boolean: An 8-bit unsigned integer with value 0 or 1.
• opaque: A sequence of binary data.
• time: Same representation as integer.
• objlnk: Two 16-bit unsigned integers, one beside the other. The first one is the object ID and the second is the Object Instance ID.

Refer to OMA Lightweight Machine to Machine Technical Specification for data type specifications.

Note: You must register the protocol translator to Edge Core before registering devices to it and initiating the write operation.

Parameter device (required)

• Type: object
• Description: The device Object containing the endpoint device LwM2M Object and Resources.

Result

A successful write operation returns an ok response.

Errors

A failed write operation returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "write",
  "params": {
    "deviceId": "device-id-1",
    "objects": [{
      "objectId": 3306,
      "objectInstances": [{
        "objectInstanceId": 0,
        "resources": [{
          "resourceId": 5700,
          "operations": 3,
          "type": "float",
          "value": "QEj1ww=="
        }]
      }]
    }]
  }
}

Tip: The operations key is bit-coded, and the value 0x01 | 0x02 = 0x03 indicates that the read and write operations are allowed.

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -30101,
    "data": "Write value failed. Failed to update device values from json.",
    "message": "Illegal value."
  }
}

Certificate renewal list set (method: `certificate_renewal_list_set`)

To be able to renew certificates and get certificate renewal notifications, use the certificate_renewal_list_set API set the list of certificates that the protocol translator wants to operate on, either by receiving renewal results for a certificate or by performing a certificate renewal.

Parameter certificates (required)

• Type: string list
• Description: The list of certificate names.

Result

A successful setting of the certificate renewal list returns an ok response.

Errors

A failed setting of the certificate renewal list returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "certificate_renewal_list_set",
  "params": {
    "certificates": ["DLMS", "LWM2M"]
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing 'certificates' field or it is of wrong type, should be array.",
    "message": "Invalid params"
  }
}

Renew certificate (method: `renew_certificate`)

Requests the certificate to be renewed. Use the Certificate renewal list set API to add the certificate to the renewal list.

Parameter certificate (required)

• Type: string
• Description: The name of the certificate to renew.

Result

An ok response is returned when certificate renewal is successfully initiated.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "renew_certificate",
  "params": {
    "certificate": "DLMS"
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing or empty 'certificate' field.",
    "message": "Invalid params"
  }
}

Get certificate (method: `crypto_get_certificate`)

Retrieve the certificate data of a specified certificate in Edge Core. The data is Base64 encoded.

Parameter certificate (required)

• Type: string
• Description: The name of the certificate to retrieve.

Result

A result response is returned when certificate data retrieval succeeds.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "get_certificate",
  "params": {
    "certificate": "DLMS"
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": { "certificate_name" : "DLMS", "certificate_data" : "MIIBvDCCAWOgAwIBAgIUWvM7X0..." }
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing or empty 'certificate' field.",
    "message": "Invalid params"
  }
}

Get public key (method: `crypto_get_public_key`)

Retrieve the public key data of a specified public key in Edge Core. The data is Base64 encoded.

Parameter public-key (required)

• Type: string
• Description: The name of the public key to retrieve.

Result

A result response is returned when public key data retrieval succeeds.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "get_public_key",
  "params": {
    "key": "DLMS"
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": { "key_name" : "DLMS", "key_data" : "MIIBvDCCAWOgAwIBAgIUWvM7X0..." }
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing or empty 'key_name' field.",
    "message": "Invalid params"
  }
}

Generate random (method: `crypto_generate_random`)

Generate and retrieve a random buffer from Edge Core. The returned buffer is Base64 encoded.

Parameter size (required)

• Type: integer
• Description: Size of random buffer to generate.

Result

A result response is returned when random buffer generation and retrieval succeeds.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "crypto_generate_random",
  "params": {
    "size": 32
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": {"data" : "DQRX/XaLUkAbR0brlyvD0wcZWmKA4P4RV9BaOl7sejw=" }
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Generate random failed. Missing or invalid size field.",
    "message": "Invalid params"
  }
}

Asymmetric sign (method: `crypto_asymmetric_sign`)

Calculate asymmetric signature on hash digest using private key from Edge Core. The returned signature value is Base64 encoded.

Parameter private_key_name (required)

• Type: string
• Description: Name of private key to use for asymmetric signature calculation.

Parameter hash_digest (required)

• Type: string
• Description: Base64 encoded hash digest to sign.

Result

A result response is returned when calculating asymmetric signature succeeds.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "crypto_asymmetric_sign",
  "params": {
    "private_key_name": "DLMS",
    "hash_digest": "DQRX/XaLUkAbR0brlyvD0wcZWmKA4P4RV9BaOl7sejw="
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": {"signature_data" : "8LH5mDp12gZh1838SCCAsWif..." }
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Asymmetric sign failed. Missing or invalid private_key_name or hash_digest field.",
    "message": "Invalid params"
  }
}

Asymmetric verify (method: `crypto_asymmetric_verify`)

Verify asymmetric signature on hash digest using public key from Edge Core.

Parameter public_key_name (required)

• Type: string
• Description: Name of public key to use for asymmetric signature verification.

Parameter hash_digest (required)

• Type: string
• Description: Base64 encoded hash digest to verify.

Parameter signature (required)

• Type: string
• Description: Base64 encoded signature to verify.

Result

An ok response is returned when verification is successful.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "crypto_asymmetric_verify",
  "params": {
    "public_key_name": "DLMS",
    "hash_digest": "DQRX/XaLUkAbR0brlyvD0wcZWmKA4P4RV9BaOl7sejw=",
    "signature": "8LH5mDp12gZh1838SCCAsWif..."
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Asymmetric verify failed. Missing or invalid public_key_name, hash_digest or signature field.",
    "message": "Invalid params"
  }
}

ECDH key agreement (method: `crypto_ecdh_key_agreement`)

Perform ECDH key agreement using provided peer public key and private key from Edge Core.

Parameter private_key_name (required)

• Type: string
• Description: Name of private key to use for ECDH key agreement.

Parameter peer_public_key (required)

• Type: string
• Description: Base64 encoded DER format peer public key.

Result

A result response is returned when ECDH key agreement is successful.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "crypto_ecdh_key_agreement",
  "params": {
    "private_key_name": "DLMS",
    "peer_public_key": "DQRX/XaLUkAbR0brlyvD0wcZWmKA4P4RV9BaOl7sejw="
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": {"shared_secret": "8LH5mDp12gZh1838SCCAsWif..."}
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "ECDH key agreement failed. Missing or invalid private_key_name or peer_public_key field.",
    "message": "Invalid params"
  }
}

Certificate enrollment (method: `est_request_enrollment`)

Perform Enrollment Over Secure Transport (EST) enrollment of a certificate.

Parameter certificate_name (required)

• Type: string
• Description: Name of certificate to enroll.

Parameter csr (required)

• Type: string
• Description: Certificate signing request in DER format and Base64 encoded.

Result

A result response is returned when the certificate enrollment is successful. The certificate_data field of the result object is an array of certificates. The array can contain multiple items when the enrollment result is a certificate chain.

Errors

An error response is returned if something goes wrong.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "est_request_enrollment",
  "params": {
    "certificate_name": "DLMS",
    "csr": "MIIBvDCCAWOgAwIBAgIUWvM7X0..."
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": {"certificate_data": ["8LH5mDp12gZh1838SCCAsWif...", "..."]}
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -30000,
    "data": "EST enrollment request failed. Memory allocation failed.",
    "message": "Protocol translator API internal error."
  }
}

Expected methods from the protocol translator

The protocol translator can react to messages sent by Edge Core. Currently, the protocol translator should react to write requests with execute or write operation. Also it should be ready to receive certificate renewal notifications.

Method `write`

You need to implement this method for write operations initiated towards translated endpoints.

A put or execute operation to endpoint device Resources is performed with the write method that the protocol translator implements.

Note: The value, regardless of the LwM2M type, must be Base64-encoded. This is required to support binary content.

Note: You must register the protocol translator and the device to Edge Core to receive write calls.

Receiving a write operation on a Resource

The operation member has value 0x02. This indicates the write operation.

The value member contains the new value for the Resource.

Edge Core writes the values in the widest possible format for precision. Edge Core does not know the data type size that the device endpoints use. The following data size and format must be supported:

• string: UTF-8.
• integer: a binary signed integer in network byte-order (64 bits).
• float: IEEE 754-2008 floating point value in network byte-order (64 bits).
• boolean: An 8-bit unsigned integer with value 0 or 1.
• opaque: A sequence of binary data.
• time: Same representation as integer.
• objlnk: Two 16-bit unsigned integers, one beside the other. The first one is the Object ID and the second is the Object Instance ID.

Refer to the OMA Lightweight Machine to Machine Technical Specification for data type specifications.

Receiving an execute operation on the resource

The operation member has value 0x04. This indicates the execute operation.

The execute operation may contain arguments in the value member. The OMA Lightweight Machine to Machine Technical Specification defines the argument syntax. For the protocol translator and Edge Core, the syntax and formatting of the execute arguments is not enforced. Implementations can define their own format, but we recommend that you use the syntax in the OMA Lightweight Machine to Machine Technical Specification.

Parameter write (required)

• Type: object
• Description: The write operation data.

Result

A successful write operation returns an ok response.

Errors

A failed write operation returns an error response.

Example request received

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "write",
  "params": {
    "operation": 2,
    "uri": {
      "deviceId": "device-id-1",
      "objectId": 3306,
      "objectInstanceId": 0,
      "resourceId": 5700
    },
    "value": "QCg9cKPXCj0="
  }
}

Tip: The operation key is bit-coded, and the value 0x02 indicates that the write operation is allowed.

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Method `certificate_renewal_result`

Edge Core sends this request to the protocol translator when a certificate renewal initiated either by the cloud or the protocol translator completes. To receive this notification, the protocol translator client must have subscribed to the certificate being renewed. See Certificate renewal list set.

The protocol client must respond to this request with a success or failure.

Parameter certificate (required)

• Type: string
• Description: The name of the certificate.

Parameter initiator (required)

• Type: int
• Description: Specifies which entity initiated the certificate renewal.
  • 0 for PT initiated renewal.
  • 1 for cloud initiated renewal.

Parameter status (required)

• Type: int
• Description: Specifies the outcome of the certificate renewal.
  • When the certificate certificate renewal completes successfully, the status is 0.
  • If an error occurs, the status is non-zero. The value is one of the codes in ce_status_e enums in certificate-enrollment-client/ce_status.h.

Parameter description (required)

• Type: string
• Description: Specifies the outcome of the certificate renewal. For example CE_STATUS_SUCCESS (same as status 0) or CE_STATUS_FORBIDDEN_REQUEST (status 1294).

Example request received

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "certificate_renewal_result",
  "params": {
    "certificate": "DLMS",
    "description": "CE_STATUS_SUCCESS",
    "initiator": 0,
    "status": 0
  }
}

Example success response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -30000,
    "message": "Catastrophical failure"
  }
}