APIs Device to Cloud Integrate Applications General concept

Integrate application endpoints

Device to Cloud can integrate different application types and their communication protocols and data formats.

Use oneM2M API to add application endpoints

In Device to Cloud your application is represented as Application Entity AE resource.

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

{
   "m2m:ae": {
    "rn": "myApplication",
    "api": "NmyApplication",
    "lbl": [ "type:d2c", "d2c:1.0", "EndpointType:<APPLICATION_TYPE>" ]
  }
}

HTTP/1.1 201 Created
  "user-agent": "axios/1.7.4",
  "content-length": "318",
  "accept": "application/json, text/plain, */*",
  "accept-encoding": "gzip, compress, deflate, br",
  "content-type": "application/json",
  "request-context": "appId=cid-v1:",
  "request-id": "|ad...91.",
  "traceparent": "00...01",
  "x-forwarded-for": "...",
  "x-forwarded-host": "...",
  "x-forwarded-proto": "https",
  "X-M2M-Origin": "CmyApplication",
  "x-m2m-ri": "06f...e4",
  "x-m2m-rvi": "3",
  "x-ms-request-id": "ad1...d9",
  "x-ms-request-root-id": "|ad1...d9.f6...91."

{
    "m2m:ae": {
    "api": "NmyApplication",
    "poa": null,
    "rn": "myApplication",
    "ty": 2,
    "ri": "66fe6b02baa471e374bd0041",
    "aei": "CmyApplication",
    "pi": "myTenant",
    "ct": "20241003T095930,861000",
    "lt": "20241003T095930,861000"
    }
}

Parameters:

  • api is the identifier of the application. The first character of the ID shall be a capital ‘N’ (for IDs not defined by a registration authority).
  • lbl (labels) type:d2c specifies: This AE is in scope for Device to Cloud. Refer the following pages for supported APPLICATION_TYPE values.
  • rn (Resource Name) is a unique identifier used in subsequent requests to refer to this specific entity.
  • In Content-Type, ty=2 defines the resource type of “Application Entity” within oneM2M (every entity has its own resource type).

Behind the scenes, a default device group for all new Device to Cloud AEs will be created. This default device group will be named appEntityNameDefaultGroup and rn (resourceName) if the AE is added to the the group.

Modify the application

By modifying request, you can change the data inside application entity (AE )

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

{
  "m2m:ae": {
    "lbl": [ "EndpointType:<APPLICATION_TYPE>" ]
  }
}

  HTTP/1.1 200 OK
  Date: Tue, 03 Dec 2024 09:12:07 GMT
  Content-Type: application/json; charset=utf-8
  Content-Length: 267
  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:ae": {
    "api": "NmyApplication",
    "poa": null,
    "rn": "myApplication",
    "ty": 2,
    "ri": "674ecb2387b651839a70a074",
    "aei": "CmyApplication",
    "pi": "myTenant",
    "ct": "20241203T091059,453000",
    "lt": "20241203T091207,484000",
    "tsn": null
  }
}

Parameters:

  • api is the identifier of the application. The first character of the ID shall be a capital ‘N’ (for IDs not defined by a registration authority).
  • rn (Resource Name) is a unique identifier used in subsequent requests to refer to this specific entity.
  • In Content-Type, ty=2 defines the resource type of “Application Entity” within oneM2M (every entity has its own resource type).

Retrieve application info

Retrieve an application entity (AE ):

  • Request
  • Response
GET {{API_URL}}/myApplication HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}
Cache-Control: no-cache

HTTP/1.1 200 OK
Date: Fri, 31 Jan 2025 12:25:55 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 254
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:ae": {
    "api": "NmyApplication",
    "poa": null,
    "rn": "myApplication",
    "ty": 2,
    "ri": "6792415c5baf99a8eee604e6",
    "aei": "CmyApplication",
    "pi": "myTenant",
    "ct": "20250123T131716,722000",
    "lt": "20250123T131716,722000"
  }
}

Retrieve device info

Retrieve device information like device model, manufacturer, SIM, credentials, etc. Information is added as sub-objects of type Device Info, SIM or Credentials:

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

HTTP/2 200 OK
date: Tue, 05 May 2026 15:16:55 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-05T15:16:55.626Z
x-m2m-rsc: 2000
x-azure-ref: 20260505T151654Z-184d7b9bf7dtp9rwhC1FRAdsfg0000000r9g000000002zu7
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: e88d48d9b9a9953e192a2331373830
vary: Origin
x-kong-upstream-latency: 682
x-kong-proxy-latency: 2
x-kong-request-id: d9bf2b2106dd0b0e513d4e1cc368b800
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 1216
x-http2-stream-id: 3

{
  "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=="
      }
    ]
  }
}

Create a subscription group for devices

You can receive device messages and notifications about various events.

Device groups let you define which device data is passed on to applications.

To get information about node resource name or an AE resource name .

A group can contain multiple applications and as many devices as you need:

Of course, you can add one application to multiple groups.

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

{
    "dtiot:devGr": {
        "cnd": "com.telekom.iot.orchestrator.deviceGroup",
        "rn": "myDeviceGroup",
        "nds": [ "testDevice","<device_rn_2>", "...", "..." ],
        "aes": [ "testAppEntity" ],
        "lbl": [ "d2c:1.0"]
    }
} 

HTTP/2 201 Created
date: Tue, 05 May 2026 15:52:52 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-05T15:52:52.598Z
x-m2m-rsc: 2001
x-azure-ref: 20260505T155252Z-1698948dff4sfch2hC1FRA1ndn0000000qn0000000011h4v
x-cache: CONFIG_NOCACHE
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: e88d48d9b9a9953e192a2333323235
vary: Origin
x-kong-upstream-latency: 275
x-kong-proxy-latency: 3
x-kong-request-id: a316b673f41b5b0a417a8d1702f13b08
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 315
x-http2-stream-id: 3

  {
  "dtiot:devGr": {
    "cnd": "com.telekom.iot.orchestrator.deviceGroup",
    "rn": "myDeviceGroup",
    "nds": [
      "testDevice", "<device_rn_2>", "...", "..."
    ],
    "aes": [
      "testAppEntity"
    ],
    "ty": 28,
    "cr": "CmyDeviceGroup",
    "st": 0,
    "ri": "69fa125412346f947f0c8222",
    "pi": "680128d474f6cb71f6fe8e86",
    "ct": "20260505T155252,565000",
    "lt": "20260505T155252,565000"
  }
}

Parameters:

  • ty=28 = flexContainer
  • rn = resource name = the group name

Delete application

By deleting an application entity (AE ), all related data subscriptions for the device to the application entities are removed:

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

HTTP/1.1 200 OK
  Date: Mon, 02 Dec 2024 21:01:14 GMT
  Content-Type: text/plain; charset=utf-8
  Content-Length: 0
  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

{}

Remove a device group

By removing a device group, all related data subscriptions for the nodes to the AEs are removed:

  • received-msg subscription
  • error-msg subscription
  • Request
  • Response
DELETE {{API_URL}}/device-group/myDeviceGroup HTTP/2
Accept: application/json
Content-Type: application/json;ty=28
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
  Date: Mon, 02 Dec 2024 21:01:14 GMT
  Content-Type: text/plain; charset=utf-8
  Content-Length: 0
  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

{}

Update a device group

Device groups let you add devices and application entities.

To get information about node resource name or an AE resource name .

A group can contain multiple applications and as many devices as you need:

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

{
    "dtiot:devGr": {
        "nds": [ "testDevice","<device_rn_2>", "...", "..." ],
        "aes": [ "testAppEntity", "<ae_rn_2>", "...", "..." ]
    }
} 

HTTP/2 200 OK
date: Tue, 05 May 2026 16:00:31 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-05T16:00:31.477Z
x-m2m-rsc: 2004
x-azure-ref: 20260505T160031Z-184d7b9bf7dfhrxrhC1FRAmzt80000000rw000000000b4zy
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: 004bb402421e3e843ec3233138353432
vary: Origin
x-kong-upstream-latency: 154
x-kong-proxy-latency: 5
x-kong-request-id: 3b44f03d8c8da5404af4b85b4caf3c0e
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 333
x-http2-stream-id: 3
{
  "dtiot:devGr": {
    "cnd": "com.telekom.iot.orchestrator.deviceGroup",
    "rn": "myDeviceGroup",
    "nds": [
      "testDevice","<device_rn_2>", "...", "..."
    ],
    "aes": [
      "testAppEntity", "<ae_rn_2>", "...", "..." 
    ],
    "ty": 28,
    "cr": "CmyDeviceGroup",
    "st": 1,
    "ri": "69fa125412346f947f0c8222",
    "pi": "680128d474f6cb71f6fe8e86",
    "ct": "20260505T155252,565000",
    "lt": "20260505T160031,468000"
  }
}

Error handling

If an error occurs during handling CRUD operations with applications/groups, it will be written to logs container. 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 identifier of the entity which caused the error (e.g. group ID, application entity ID, etc.).

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: Tue, 05 May 2026 16:03:23 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-05T16:03:23.385Z
x-m2m-rsc: 2000
x-azure-ref: 20260505T160323Z-1698948dff4rrqmbhC1FRA1tz00000000cvg00000000b4hw
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: 004bb402421e3e843ec3233138363531
vary: Origin
x-kong-upstream-latency: 164
x-kong-proxy-latency: 4
x-kong-request-id: 14df566aa8b3dc44f357824c58e8d65c
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 523
x-http2-stream-id: 3

{
  "m2m:cin": {
    "con": {
      "identifier": "myDeviceGroup",
      "type": "group processing failed",
      "service": "d2c-device-provisioning",
      "data": null,
      "status": {
        "code": 500,
        "message": "internal server error",
        "detail": "Internal server error: device-provisioning unable to update group data."
      }
    },
    "cnf": "application/json:0",
    "ty": 4,
    "cs": 268,
    "st": 990,
    "cr": "CmyApplication",
    "rn": "d7ac9068-53a6-4067-aa4b-0e9e01510119",
    "ri": "69fa142112346f947f0c82a8",
    "pi": "69cb1038f2472ed93915eb03",
    "ct": "20260505T160033,662000",
    "lt": "20260505T160033,662000"
  }
}

Fields:

  • identifier — the entity identifier.
  • type — describes the error category (e.g. "group 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 — 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.

Errors summary table

Status CodeStatus MessageDescription
500internal server errorInternal server error: subscription creation failed.
500internal server errorInternal server error: device-provisioning unable to get group data.
500internal server errorInternal server error: default group creation failed.
500internal server errorInternal server error: device-provisioning unable to update group data.
500internal server errorInternal server error: device-provisioning unable to get data of the group.
500internal server errorInternal server error: unexpected error occurred.
500internal server errorInternal server error: device-provisioning unable to get application entity data.
500internal server errorInternal server error: device-provisioning unable to update data group in table.
500internal server errorInternal server error: device-provisioning unable to delete subscription data.
500internal server errorInternal server error: device-provisioning unable to clean up group data in table.
500internal server errorInternal server error: device-provisioning unable to create group data.
500internal server errorInternal server error: device-provisioning unable to clean up group data.
500internal server errorInternal server error: device-provisioning unable to process notification data.