APIs Device to Cloud Get started

Step-by-step tutorial

This tutorial will guide you through the typical steps of using the Device to Cloud API.

Prepare:

  1. Register your application in T IoT Hub to get credentials (see below ).
  2. Use the credentials to get an API Token (see below ).
  3. Register your client app in oneM2M as well, so that you can use it as “X-M2M-Origin” (see below ).

Onboard your IoT devices:

  1. Prepare your IoT devices to connect to Device to Cloud.
  2. Request the onboarding of IoT devices.
  3. Check the onboarding status .

Do some initial device management:

  1. Modify the device data
  2. Add some device properties .

Communicate with your IoT devices:

  1. Start sending commands to the LwM2M device …
  2. … and receive data back from the device.
  3. Integrate your 1st application with its webhook endpoint.
  4. Route IoT messages to your application by configuring a device group
NOTE
You can download a file containing all API calls.

Register your application in T IoT Hub

To use the API from your application (or by command line), register an application in T IoT Hub.

Use our Application Access Management to create credentials and get:

  • the Token Issuer URL (AUTH_URL)
  • the Client ID (CLIENT_ID)
  • the Secret (CLIENT_SECRET)
  • the API URL (API_URL)

Get API token

To use the oneM2M API for Device to Cloud, authenticate and retrieve an access token .

  • Request
  • Response
POST {{AUTH_URL}} HTTP/2
content-type: application/x-www-form-urlencoded
accept: application/x-www-form-urlencoded, application/json
authorization: Basic {{iot_hub_client_id}} {{iot_hub_client_secret}}

grant_type=client_credentials

HTTP/1.1 200 OK
Date: Thu, 20 Mar 2025 08:58:53 GMT
Content-Type: application/json
Content-Length: 1479
Connection: close
cache-control: no-store
pragma: no-cache
referrer-policy: no-referrer
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
vary: Origin

{
  "access_token": "eyJhbGc...CTROHIpg",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "client-origin profile email"
}

Use the access_token in the response in all subsequent calls as the value of the ACCESS_TOKEN variable.

To use the API: Register your client

In oneM2M you need the create an AE (Application Entity) in the CSE (Common Service Entity) .

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

{
    "m2m:ae": {
        "api": "NTestApp",
        "rn": "TestApp"
	}
}

HTTP/1.1 201 Created
Date: Thu, 20 Mar 2025 10:00:54 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 171
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:ae": {
    "api": "NTestApp",
    "rn": "TestApp",
    "ty": 2,
    "ri": "67dbe75676628f9e86002ec2",
    "aei": "CTestApp",
    "pi": "eos",
    "ct": "20250320T100054,049000",
    "lt": "20250320T100054,049000"
  }
}

In all following API calls this “CTestApp” is used as X-M2M-Origin header field.

  • X-M2M-RI represents the Request Identifier (M2M-Request-ID) that is sent in a request and added to a response. It is highly recommended to generate a UUID per request. If a request is still pending, a 2nd request with the same ID may be rejected.
  • The api is the identifier of the application. The first character of the ID shall be a capital ‘N’ (for non-registration authority defined IDs).
  • The rn (Resource Name) represents the unique identifier that will be used in further requests for identifying this particular entity.

Please use the api and rn values above as is, since we use these in all subsequent examples.

Hint:

Visual Studio Code has a great REST Client plug-in to test requests.

Just copy/paste the HTTP code into e.g. a api_test.http file, set the variables (@API_URL = <Your API URL> …) and you can test the API just by clicking “Send Request”. You can also download our .http file containing all API calls from this tutorial.

As an added value, you can easily generate code in your preferred language and library by pressing “Clt + Alt + C”.

Next steps

Configure IoT devices to connect to Device to Cloud and use the oneM2M API to

  1. onboard IoT devices ,
  2. send and receive data from a device , and
  3. integrate applications