APIs Device to Cloud Lwm2m Devices Onboard devices

LwM2M Device provisioning request

Devices are represented as node instances in oneM2M. You can request to onboard a list of nodes by adding a “/device-provisioning/request”:

  • Request
  • Response
POST {{API_URL}}/device-provisioning/request HTTP/2
Accept: application/json
Content-Type: application/json;ty=28
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
    "dtiot:noPRt": {
        "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
        "rn": "myProvisioningRequest01",
        "opern": 1,
        "reqLt": [
            {
                "ni" : "urn:gsma:imei:3519...88011",
                "noRNe": : "myLwM2M-Device01",
                "ICCID" : "898...20111",
                "profe" : "SCS-LwM2M",
                "lbl": [
                  "d2c:1.0"
                ],
                "nCr": [
                  "psk-id:myLwM2M-Device01Id",
                  "psk:dGVzdDEyMw=="
                ],
                "nodeDeviceGroups": ["myDeviceGroup"],
                "ndvi": {
                    "rn": "device-info",
                    "mgd": 1007,
                    "man": "ACME",
                    "dty": "Some sensor",
                    "mod": "12345",
                    "dlb": "d2c:1.0",
                    "dc": "measured something"
                  }
            }
        ]
    }
}

HTTP/1.1 201 Created
Date: Thu, 21 Nov 2024 09:17:48 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 533
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "dtiot:noPRt": {
    "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
    "rn": "myProvisioningRequest01",
    "opern": 1,
    "reqLt": [
      {
        "ni": "urn:gsma:imei:3519...88011",
        "noRNe": "myLwM2M-Device01",
        "ICCID": "898...20111",
        "profe": "SCS-LwM2M",
        "lbl": [
          "d2c:1.0"
        ],
        "ndvi": {
          "rn": "device-info",
          "mgd": 1007,
          "man": "ACME",
          "dty": "Some sensor",
          "mod": "12345",
          "dlb": ["d2c:1.0","some:label"],
          "dc": "measured something" 
        },
        "nCr": [
          "psk-id:myLwM2M-Device01Id",
          "psk:dGVzdDEyMw=="
        ],
        "nDGr": [
          "myDeviceGroup"
        ]
      }
    ],
    "ty": 28,
    "cr": "CmyApplication",
    "st": 0,
    "ri": "67...2a",
    "pi": "671...3f",
    "ct": "20241121T091747,984000",
    "lt": "20241121T091747,984000"
  }
}

Parameters:

  • In Content-Type header: ty=28 means “flexContainer”
  • cnd - containerDefinition
    • Contains an identifier reference (URI) to the “flexContainer” schema definition which shall be used by the CSE to validate the syntax of the FlexContainer resource
  • operation: 1=provision
  • requestList: Array of “node” instances with
    • nodeID: The value shall be a valid nodeID string in one of the following formats: urn:gsma:imei:<imei> or urn:x-dtiot:dev:sn:<string with the serial number from device>
    • nodeResourceName: This is the “Device ID” which e.g. is used in Device Groups to identify the device.
    • ICCID (optional): ICCID of the SIM Card that will be used by the device.
    • profile: Defines the IoT platform where the device is onboarded: SCS-LwM2M for LwM2M Devices.
    • labels: An array of strings. The label "d2c:1.0" is mandatory for “Device to Cloud” IoT devices. Example: ["color:red","manufacturer:ACME","d2c:1.0"]
    • nodeCredentials (only mandatory for LwM2M Devices, profile:SCS-LwM2M): An array of strings, e.g. ["psk-id:xyz","psk:secret-as-base64"]. The psk-id must be unique (e.g. UUID) and please never reuse a psk-secret between devices.
    • nodeDeviceInfo (optional): device-related information
    • nodeDeviceGroups (optional) Represents an array containing a list of groups where devices to be added to the groups
  • X-M2M-RI: Represents a unique request ID. Please don’t use 123!! If you have a support request you can help us by providing us the related request ID.

This table represents Device Info Management Object possible variation.

ScenarioExpected Behaviour
A Provisioning Request is submitted with a node and a Management Object for Device Information with rn="someCustomerName".• The node with the specified nodeResourceName is created.
• A Management Object for Device Information containing all fields provided in the request and with rn="someCustomerName" is created.
• An additional empty Management Object with rn="device-info" is created. Only the necessary fields are included; unnecessary fields of the Device Information object are omitted.
A Provisioning Request is submitted with a node and a Management Object for Device Information with rn="device-info".• The node with the specified nodeResourceName is created.
• A Management Object for Device Information containing all fields provided in the request and with rn="device-info" is created.
A Provisioning Request is submitted with a node and a Management Object for Device Information without an rn specified.• The node with the specified nodeResourceName is created.
• A Management Object for Device Information containing all fields provided in the request and with rn="device-info" is created.
A Provisioning Request is submitted with a node but without a Management Object for Device Information.• The node with the specified nodeResourceName is created.
• An empty Management Object with rn="device-info" is created. Only the necessary fields are included; unnecessary fields of the Device Information object are omitted.

Device provisioning response

The system will process your device provisioning request and the result is available in the “/device-provisioning/response”:

  • Request
  • Response
GET {{API_URL}}/device-provisioning/response/{{responseToRequest-69...7f}} HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
Date: Thu, 05 Dec 2024 09:19:49 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 653
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "dtiot:prRRe": {
    "cnd": "com.telekom.iot.orchestrator.provisioningRequestResponse",
    "rn": "responseToRequest-69...7f",
    "reqRD": "69...7f",
    "resSs": 2,
    "geEMe": "Total to be provisioned: 1; Successfully processed: 0; Errors: 1",
    "inEMs": [
      {
        "niD": "ur...116",
        "errMe": "device profile not supported"
      }
    ],
    "ty": 28,
    "crr": "CmyApplication",
    "st": 0,
    "ri": "67...ba7",
    "pi": "67...f32",
    "ct": "20241205T074006,516000",
    "lt": "20241205T074006,516000"
  }
}

Parameter:

  • resourceName: the prefix “responseToRequest-” must be used alongside with resource id of the device-provisioning request (for example, “responseToRequest-67…56”)

Possible known error cases

Possible known error cases that could happen, when we receive a device-provisioning request

#Error Case / ConditionError Message / Behavior
1nodeID cannot be empty“nodeID can not be empty.”
2nodeID must be unique“Node with nodeID urn:gsma:imei:3519345467883041 already exists, The existed node resourceName = device3036”
3nodeResourceName cannot be empty“onboarding failed on missing node resource name”
4nodeResourceName must be unique“device3030 device already exists”
5nodeCredentials cannot be empty (must include psk-id and psk)“psk info is missing”
6Duplicate psk-id (credential conflict)“conflicting credentials for AddEndPointRequest device3007”

Check the device node

Each time your LwM2M device makes an LwM2M register request to Device to Cloud, D2C requests LwM2M objects 3 (Device) and 6 (Location) from your LwM2M device.

D2C then stores some values from objects 3 and 6 in a device info resource with the name device-info in your device node, e.g:

  • manufacturer
  • device model
  • hardware version
  • firmware version
  • GPS location

You can retrieve this device-info :

  • Request
  • Response
GET  {{API_URL}}/myLwM2M-Device01?ty=14&rcn=4 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
Date: Thu, 05 Dec 2024 07:57:10 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1462
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "m2m:nod": {
    "ni": "urn:gsma:imei:999934546781019",
    "lbl": [
      "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
      "d2c-uplink-property_AssetId:1234546",
      "d2c-uplink-property_Room:1234",
      "d2c:1.0",
      "profile:SCS-LwM2M",
      "ICCID:99982280000004491019",
      "d2c_lifecycle⚱gsma:imei:999934546781019",
      "d2c_resource_/3303/0/5700:ac387081-41ec-4819-8be4-9152882d6b1e"
    ],
    "rn": "myLwM2M-Device01",
    "ty": 14,
    "ri": "6980f7a856c78d1c4957fa11",
    "pi": "myTenant",
    "ct": "20260202T191448,109000",
    "lt": "20260223T092727,644000",
    "m2m:crds": [
      {
        "dc": "cred",
        "mgd": 1029,
        "rn": "credentials",
        "lbl": [
          "d2c:1.0"
        ],
        "ty": 13,
        "ri": "6980f7a856c78d1c4957fa16",
        "pi": "6980f7a856c78d1c4957fa11",
        "ct": "20260202T191448,369000",
        "lt": "20260202T191448,369000",
        "crid": "myLwM2M-Device01_psk",
        "crse": "c29tZU5ld1JhbmRvbUQyY1Bhc3N3b3Jk"
      }
    ],
    "m2m:dvi": [
      {
        "rn": "device-info",
        "mgd": 1007,
        "man": "Leshan Demo Device",
        "dty": "device",
        "mod": "Model 500",
        "dlb": "urn:gsma:imei:999934546781019",
        "dc": "a comment",
        "lbl": [
          "d2c:1.0"
        ],
        "ty": 13,
        "ri": "6980f7aa56c78d1c4957fa19",
        "pi": "6980f7a856c78d1c4957fa11",
        "ct": "20260202T191450,996000",
        "lt": "20260505T110110,495000",
        "dvnm": "Leshan Demo Device",
        "fwv": "1.0.0",
        "loc": "geo:-84.0,-138.0",
        "ptl": [
          "LWM2M"
        ],
        "swv": "1.0.2",
        "syst": "afnN9Q=="
      }
    ]
  }
}

Modify the device node

You can update the device-info of the device by providing device resource name in path, e.g. the latitude and longitude of the geographic location:

  • Request
  • Response
PUT {{API_URL}}/myLwM2M-Device01/device-info HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "m2m:dvi": {
          "loc": "geo:48.861045,2.335765"
        }
}

HTTP/1.1 200 OK
Date: Thu, 21 Nov 2024 09:07:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 445
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "m2m:dvi": {
    "loc": "geo:48.861045,2.335765",
    "mod": "Model 500",
    "man": "Leshan Demo Device",
    "dty": "device",
    "dlb": "urn:gsma:imei:999934546781019",
    "dc": "a comment",
    "lbl": [
      "d2c:1.0"
    ],
    "mgd": 1007,
    "ty": 13,
    "rn": "device-info",
    "ri": "673e...2b",
    "pi": "673e...29",
    "ct": "20241121T090606,785000",
    "lt": "20241121T090704,392000",
    "dvnm": "Leshan Demo Device",
    "fwv": "1.0.0",
    "ptl": [
      "LWM2M"
    ],
    "swv": "1.0.2",
    "syst": "afnN9Q=="
  }
}

Parameters:

  • loc: geographic location

Working with device properties

Use the ‘Device Properties’ option to add additional information to a device and for filtering.

There are two types of device properties:

  1. general properties
  2. uplink properties

General properties are key/value pairs where you can add additional data to your device, e.g.

  • asset id
  • building address, floor, room number
  • additional type info
  • last battery change date

Uplink properties are key/value pairs which are added to each device message. This simplifies the integration into your systems, since you can avoid complex lookups when processing the data. Uplink properties are identified by key names starting with prefix “d2c-uplink-property_”.

Example request to add device properties as labels in lbl:

  • Request
  • Response
PUT {{API_URL}}/myLwM2M-Device01 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "m2m:nod": {
    "lbl": [
      "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
      "LastMaintanance:12.03.2024 12:34",
      "d2c-uplink-property_AssetId:1234546",
      "d2c-uplink-property_BuildingId:BER-76545",
      "d2c-uplink-property_Status:PendingInstallation",
      "profile:SCS-LwM2M",
      "d2c:1.0"
    ]
  }
}

HTTP/1.1 200 OK
Date: Wed, 26 Feb 2025 18:37:54 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 384
Connection: keep-alive
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "m2m:nod": {
    "ni": "urn:gsma:imei:999934546781019",
    "lbl": [
      "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
      "LastMaintanance:12.03.2024 12:34",
      "d2c-uplink-property_AssetId:1234546",
      "d2c-uplink-property_BuildingId:BER-76545",
      "d2c-uplink-property_Status:PendingInstallation",
      "profile:SCS-LwM2M",
      "d2c:1.0"
    ],
    "rn": "myLwM2M-Device01",
    "ty": 14,
    "ri": "6980f7a856c78d1c4957fa11",
    "pi": "myTenant",
    "ct": "20260202T191448,109000",
    "lt": "20260223T092727,644000",
  }
}

Important: The label "d2c:1.0" and "profile:SCS-LwM2M" are mandatory for “Device to Cloud” LwM2M devices in DMO. Please ensure that it is always retained in update operations.

Delete the device node

A device can be deleted by deleting its node . The system will clean up all related objects (sent/received messages, groups, …).

  • Request
  • Response
DELETE {{API_URL}}/myLwM2M-Device01 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
Date: Thu, 21 Nov 2024 09:44:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 0
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

Error handling

If an error occurs during provisioning/handling CRUD operations with device, It will be written to error-msg and logs containers. error-msg container is belonged to particular device, while logs container is shared for all devices.
The error message contains the details of the error, such as error code, error message, error details and device identifier.

Example of error message in error-msg container for a particular device

  • Request
  • Response
GET {{API_URL}}/device-communication/myLwM2M-Device01/error-msg/la HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/2 200 OK
date: Wed, 06 May 2026 18:39:45 GMT
content-type: application/json; charset=utf-8
request-context: appId=cid-v1:
x-service-responder: device-management-orchestrator
x-m2m-ri: 123
x-m2m-rvi: 4
x-m2m-ot: 2026-05-06T18:39:45.501Z
x-m2m-rsc: 2000
x-azure-ref: 20260506T183945Z-1698948dff4rhdk2hC1FRA1qrw0000000vx00000000062f8
x-cache: CONFIG_NOCACHE
accept-ranges: bytes
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-content-type-options: nosniff
x-frame-options: DENY
x-xss-protection: 0
referrer-policy: no-referrer
x-tardis-traceid: e73dacf181ec59495ca52336373930
vary: Origin
x-kong-upstream-latency: 241
x-kong-proxy-latency: 5
x-kong-request-id: 3325a5457c5e4b2794011e43b3cbfc5b
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 629
x-http2-stream-id: 3
{
  "m2m:cin": {
    "con": {
      "nodeResourceName": "myLwM2M-Device01",
      "nodeID": "urn:gsma:imei:999934546781019",
      "data": "",
      "status": {
        "code": 500,
        "message": "internal server error",
        "detail": "Internal server error: subscription creation failed."
      }
    },
    "cnf": "application/json:0",
    "ty": 4,
    "cs": 604,
    "st": 3,
    "cr": "CmyApplication",
    "rn": "a2efd14b-d5d8-41e0-9c3c-74e907abfc95",
    "ri": "69b17f068006f89d59522af0",
    "pi": "69b132f78006f89d59521efa",
    "ct": "20260311T144110,154000",
    "lt": "20260311T144110,154000"
  }
}

Fields:

  • nodeResourceName — the device ID as registered during provisioning.
  • nodeID — nodeID in one of the following formats: urn:gsma:imei:<imei> or urn:x-dtiot:dev:sn:<string with the serial number from device>
  • data — empty in case of errors not related to messages
  • status.code — HTTP-style error code.
  • status.message — short error description.
  • status.detail — detailed error message for debugging.
  • cnf — content format; "application/json:0" indicates a JSON payload.

Example of error message in logs container

  • Request
  • Response
GET {{API_URL}}/device-provisioning/logs/la HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/2 200 OK
date: Wed, 06 May 2026 18:39:45 GMT
content-type: application/json; charset=utf-8
request-context: appId=cid-v1:
x-service-responder: device-management-orchestrator
x-m2m-ri: 123
x-m2m-rvi: 4
x-m2m-ot: 2026-05-06T18:39:45.501Z
x-m2m-rsc: 2000
x-azure-ref: 20260506T183945Z-1698948dff4rhdk2hC1FRA1qrw0000000vx00000000062f8
x-cache: CONFIG_NOCACHE
accept-ranges: bytes
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-content-type-options: nosniff
x-frame-options: DENY
x-xss-protection: 0
referrer-policy: no-referrer
x-tardis-traceid: e73dacf181ec59495ca52336373930
vary: Origin
x-kong-upstream-latency: 241
x-kong-proxy-latency: 5
x-kong-request-id: 3325a5457c5e4b2794011e43b3cbfc5b
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 629
x-http2-stream-id: 3
{
  "m2m:cin": {
    "con": {
      "identifier": "urn:gsma:imei:999934546781019",
      "type": "device provisioning failed",
      "service": "d2c-device-provisioning",
      "data": "",
      "status": {
        "code": 400,
        "message": "bad request",
        "detail": "Device could not been provisioned. Check the data of device-provisioning request. psk-id or psk is missed."
      }
    },
    "cnf": "application/json:0",
    "ty": 4,
    "cs": 641,
    "stg": 2,
    "cr": "CmyApplication",
    "rn": "31af43c7-f111-4e5a-9694-7c66f5745f72",
    "ri": "69b17f068006f89d59522af1",
    "pi": "69b158c08006f89d595224b4",
    "ct": "20260311T144110,172000",
    "lt": "20260311T144110,172000"
  }
}

Fields:

  • identifier — the node identifier.
  • type — describes the error category (e.g. "device processing failed").
  • service — the service that produced the log entry (d2c-device-provisioning).
  • data — empty in case of errors not related to messages
  • status.code / status.message / status.detail — same semantics as in the error-msg container.
  • cnf — content format; "application/json:0" indicates a JSON payload.

Errors summary table

Status CodeStatus MessageDescription
400bad requestDevice could not been provisioned. Check the data of device-provisioning request. nodeResourceName is missed.
400bad requestDevice could not been provisioned. Device with the same nodeResourceName already exists.
400bad requestDevice could not been provisioned. Check the data of device-provisioning request. psk-id or psk is missed.
400bad requestdevice event could not been handled. Check the data of device. profile is missed.
400bad requestDevice could not been provisioned. Check the data of device-provisioning request. profile is missed.
500internal server errorInternal server error: subscription creation failed.
500internal server errorInternal server error: device-provisioning unable to get device data.
500internal server errorInternal server error: device-provisioning unable to create device objects.
500internal server errorInternal server error: device-provisioning unable to create device data.
500internal server errorInternal server error: device-provisioning unable to remove device subscription.
500internal server errorInternal server error: device-provisioning unable to create device subscription.
500internal server errorInternal server error: device-provisioning unable to create device data in table.
500internal server errorInternal server error: unexpected error occurred.
500internal server errorInternal server error: device-provisioning unable to update device data.
500internal server errorInternal server error: device-provisioning unable to update device properties.
500internal server errorInternal server error: device-provisioning unable to get device data from table.
500internal server errorInternal server error: device-provisioning unable to update device data in table.
500internal server errorInternal server error: device-provisioning unable to delete device data.
500internal server errorInternal server error: device-provisioning unable to process notification data.

Next step

Start sending commands to your LwM2M device and receive data back from the device.