APIs DMO API Access Control Policies

The Device Management Orchestrator (DMO) API supports the Access Control Policy resource type , which lets you control who can access resources and perform operations within your tenant. Restricting certain resources this way can be quite useful when you have a CSE with multiple AEs working on it. The approach helps separate the different roles and concerns for your Application Entities . It also makes sure only specific entities can interact with the resources that could be critical to your use-case. This page explains how to create and manage the AccessControlPolicy (ACP) resources and how to link them to your resources in order to protect them. The API’s Default Access Policy is also explained here, which is a built-in policy that can be used to enforce access control for resources that do not have an explicit (or inherited) ACP assigned.

Access Control Policy (ACP) Resource

The Access Control Policy (ACP) resource lets you define and manage access control rules for your resources. Each ACP resource contains a set of permissions that specify which Application Entities are allowed to perform specific operations on the associated resources.

For example, a typical ACP resource could look like this:

{
  "m2m:acp": {
    "rn": "acme-admin-acp",
    "pv": {
      "acr": [
        {
          "acor": [
            "S-ws-berlin-001",
            "S-ft-munich-001"
          ],
          "acop": 63
        }
      ]
    },
    "pvs": {
      "acr": [
        {
          "acor": [
            "S-ws-berlin-001"
          ],
          "acop": 63
        }
      ]
    },
    "ty": 1,
    "cr": "S-ws-berlin-001",
    "ri": "6a959955e53217eee84f403e",
    "pi": "acme-iot",
    "ct": "20260831T151013,430000",
    "lt": "20260831T151013,430000"
  }
}

This example shows, that S-ws-berlin-001 and S-ft-munich-001 are both granted all permissions on the associated resources, but only S-ws-berlin-001 is granted all permissions on the ACP resource itself. This means only S-ws-berlin-001 can edit or delete the ACP or change which resources it is assigned to. The most important ACP attributes are:

  • privileges (pv): A list of permissions that define which Application Entities are permitted exactly what type of operations on the assigned resource. This is done via each privilege entry specifying the allowed operations (e.g., CREATE, RETRIEVE, UPDATE, DELETE using a bitmask represented by an integer) and the corresponding Application Entity (e.g., S-ws-berlin-001) that is granted those permissions. The other attributes of access control rules (such as acco, accod or acaf) are not currently supported by DMO API. This attribute has the following structure:

    • accessControlRule (acr): A list of access control rules. As long as there is at least one access control rule that allows the requested operation for the given AE, the operation is allowed. They are represented by [accessControlOriginators, accessControlOperations] tuples:
      • accessControlOriginators (acor): A list of Application Entities that are granted the permissions defined in the acop attribute. To correctly reference an Application Entity here, you need to use its AE-ID which is the same value that you need to send in the X-M2M-Origin header to identify the AE sending the request as well. It can be a specific AE-ID (e.g., S-ws-berlin-001) or the value all to allow all Application Entities.

      • accessControlOperations (acop): An integer that represents the scope of allowed operations for the Application Entities specified in acor. The operations are represented as a bitmask, where each bit corresponds to a specific operation. The following operations are supported:

        • CREATE: 1
        • RETRIEVE: 2
        • UPDATE: 4
        • DELETE: 8
        • ALL: 63 (represents all operations)

        There are two more operations defined by the oneM2M standard. These are currently accepted by the DMO API but are not enforced:

        • NOTIFY: 16 (used for subscription notifications)
        • DISCOVER: 32 (used for resource discovery)

        You can combine multiple operations by adding their corresponding values. For example, to allow both CREATE and RETRIEVE operations, you would set acop to 3 (CREATE + RETRIEVE => 1 + 2).

  • selfPrivileges (pvs): A list of permissions with the same syntax as privileges. However, these define the permissions for the ACP resource itself and the acpi attribute of other resources linked to it (see the details in Assigning ACPs to other resources section). Using these you can control which Application Entities are allowed to see or modify the access control rules of your CSE.

Requests Exempt From ACP Enforcement

For technical reasons there are several requests where the API intentionally does not enforce ACP checks. These two are:

  • AE self-registration: When an AE is being registered for the first time, the CREATE flag check on its parent is skipped.
  • CSEBase retrieval: When the CSEBase is requested via a normal retrieve (non-discovery, attributes only) request, access checks are skipped.
Subscription Creation
The only operation that requires more than one access flag check is the Subscription CREATE request. For this to be successful, the originator needs to have both CREATE and RETRIEVE permissions on the parent resource.

Assigning ACPs to other resources

Once you have already created at least one ACP resource, you can assign it to other resources in order to protect them. This is done by setting the acpi attribute of the target resource to the resource ID (e.g., 6a8c6644f9881c500060df88) or the absolute resource path (e.g., acme-iot/acme-admin-acp) of the ACP resource. The acpi attribute is a list, so you can assign multiple ACPs to a single resource if needed. When a resource has one or more ACPs assigned, the request will be granted access for the given operation if any one of the assigned ACPs permits it for the requesting Application Entity. If none of the assigned ACPs allow the operation for the requesting AE, the request will be denied with a 403 Forbidden response.

For example, to assign the acme-admin-acp ACP to a Container resource, you would include the following in the request body when creating or updating the Container:

{
  "m2m:cnt": {
    "acpi": [
      "acme-iot/acme-admin-acp"
    ]
  }
}

This will result in a resource that looks like the one below. The acpi attribute is now set to the absolute path of the ACP resource, which means that only the Application Entities specified in the ACP’s pv will be able to perform operations on this Container. In this example, both S-ws-berlin-001 and S-ft-munich-001 are allowed to access it.

{
  "m2m:cnt": {
    "rn": "routes",
    "mni": 500,
    "acpi": [
      "acme-iot/acme-admin-acp"
    ],
    "ty": 3,
    "st": 0,
    "cbs": 0,
    "cni": 0,
    "cr": "S-ft-munich-001",
    "ri": "6a95995ee53217eee84f403f",
    "pi": "6a95994ae53217eee84f403d",
    "ct": "20260831T151022,522000",
    "lt": "20260831T151022,522000"
  }
}
Example
You can check out the whole example workflow in the Example section below, which shows how to create an ACP and assign it to a Container resource.

To see an additional example request on how you might do this, please check out the example called “Protect resource with ACP” in the Nodes section of the DMO API swagger reference. You can, of course, also assign ACPs to other resource types like Containers, Content Instances, Management Objects, etc. The only exceptions from this are CSEBase and AccessControlPolicy. You are also able to set the acpi attribute on resource creation as well.

ACP inheritance

When you assign an ACP to a resource, it will also be inherited by all child resources of that resource. This means that if you assign an ACP to a Node, all Containers, Content Instances, and Management Objects under that Node will also be protected by the same ACP unless they have their own acpi attribute set. If a child resource has its own acpi attribute, it will override the inherited ACPs from its parent resource for itself and its subtree too.

Generally, when working with ACP inheritance, it is a good practice to assign ACPs to higher level parent resources (like Nodes) only and let them be inherited by child resources as much as possible, unless you have specific requirements for different access control rules on certain children. This makes access control easier to manage and helps to avoid having to set ACPs on every single resource.

Default Access Policy

The Default Access Policy is a built-in policy that, when turned on, is applied to resources that do not have an explicit (or inherited) ACP assigned. It allows only the Application Entity that created the resource (or one that was appointed as its custodian beforehand) to access it. This ensures that resources are protected by default and prevents unauthorized access. For backwards compatibility reasons, this feature is currently opt-in in DMO. You can enable the Default Access Policy by setting the enforceDefaultAcp (enDAp) attribute of the tenantInformation resource directly under the CSEBase to true. Once enabled, if a resource has no ACP assigned, the API will check if the requesting Application Entity is the creator of the resource (or its custodian) and allow full access only if it is. If the requesting AE is not the creator or custodian, the request will be denied with a 403 Forbidden response.

The creator of a resource is represented by its creator (cr) attribute. This is automatically set by the DMO API when a resource is created based on the originator (X-M2M-Origin header) of the request and cannot be modified once set. The custodian of a resource is represented by its custodian (cstn) attribute. This can be set to the AE-ID of another Application Entity that is allowed to access the resource, even if it is not the creator. If the cstn attribute is not set, the creator of the resource is used instead. The custodian can be changed only by the Application Entity that is already set as the custodian, or the creator if the custodian is not set. The custodian can also be set on resource creation by including the cstn attribute in the request body.

Automatic Custodian Appointment
For technical and backwards compatibility reasons, the first time a request enables the enforceDefaultAcp attribute, the custodian of the tenantInformation will be automatically set to the originator of the enabling request. This is only done if the tenantInformation resource has no custodian set up beforehand. This process is called automatic custodian appointment in the DMO API. This is done to ensure that the system always has an Application Entity in an “administrator” role that can modify the flag. This way it is possible to avoid accidental lockouts from the CSEBase due to ACP management.

To see an example on how to turn on the Default Access Policy feature, please check out the example called “tenantInformation (enable enDAp/nELEd flags)” in the CSEBase direct child update section of the swagger API reference.

Example

The following workflow uses the fictional ACME IoT scenario from the DMO API reference . It starts with the existing acme-iot CSEBase and its WeatherStation AE, whose AE-ID is S-ws-berlin-001. It then enables the Default Access Policy, registers the FleetTracker AE, creates an ACP that grants access to both AEs, and creates a protected routes Container for FleetTracker.

Set these variables before running the requests:

# Include the API version and CSEBase name in the URL.
API_URL="<dmo_api_url>/v3/acme-iot"
ACCESS_TOKEN="<access_token>"

Resource IDs and timestamps in the responses are assigned by DMO and will differ in your environment.

Step 1: Check the existing CSEBase and AE

Retrieve the acme-iot CSEBase and filter its child resources to AEs (ty=2). At the start of this workflow, WeatherStation is the only AE. A successful request returns HTTP 200 and X-M2M-RSC: 2000.

  • Copy & paste
  • Output
curl --location --request GET "$API_URL?rcn=4&ty=2" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-M2M-Origin: S-ws-berlin-001" \
--header "X-M2M-RI: acp-example-1" \
--header "Accept: application/json"
{
  "m2m:cb": {
    "rn": "acme-iot",
    "csi": "acme-iot",
    "cst": 1,
    "csz": [
      "application/json",
      "application/vnd.onem2m-res+json"
    ],
    "srt": [
      2,
      14,
      13,
      5,
      28,
      52
    ],
    "srv": [
      "3"
    ],
    "ty": 5,
    "ri": "acme-iot",
    "cr": "CAdmin",
    "pi": "",
    "ct": "20260824T153808,510000",
    "lt": "20260824T153808,510000",
    "m2m:ae": [
      {
        "rn": "WeatherStation",
        "api": "N-ACME-WeatherStation",
        "rr": false,
        "ty": 2,
        "ri": "6a8c6644f9881c500060df88",
        "aei": "S-ws-berlin-001",
        "cr": "S-ws-berlin-001",
        "poa": null,
        "pi": "acme-iot",
        "ct": "20260824T154156,484000",
        "lt": "20260828T140017,096000",
        "nl": "6a8c66a7f9881c500060df8b"
      }
    ]
  }
}

Step 2: Enable the Default Access Policy

Set enDAp to true on tenantInformation. Because this is the first time enforcement is enabled, DMO appoints the requesting WeatherStation AE as custodian (cstn) of tenantInformation. A successful update returns HTTP 200 and X-M2M-RSC: 2004.

  • Copy & paste
  • Output
curl --location --request PUT "$API_URL/tenantInformation" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-M2M-Origin: S-ws-berlin-001" \
--header "X-M2M-RI: acp-example-2" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '{
  "dtiot:tenIn": {
    "enDAp": true
  }
}'
{
  "dtiot:tenIn": {
    "cnd": "com.telekom.iot.orchestrator.tenantInformation",
    "backendTypes": [
      "SCS"
    ],
    "backendTypeConfig": {
      "scs": {
        "natCo": "tdg"
      }
    },
    "rn": "tenantInformation",
    "ty": 28,
    "tenantID": "acme-iot",
    "st": 1,
    "ri": "6a8c6560f9881c500060df87",
    "cr": "CAdmin",
    "pi": "acme-iot",
    "ct": "20260824T153808,513000",
    "lt": "20260831T150828,167000",
    "enDAp": true,
    "cstn": "S-ws-berlin-001"
  }
}

Step 3: Register the new AE

Register FleetTracker with the AE-ID S-ft-munich-001. AE self-registration is allowed even though the Default Access Policy is now enforced. A successful registration returns HTTP 201 and X-M2M-RSC: 2001.

  • Copy & paste
  • Output
curl --location --request POST "$API_URL" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-M2M-Origin: S-ft-munich-001" \
--header "X-M2M-RI: acp-example-3" \
--header "X-IoT-Hub-Client-Id: acme-fleet-tracker" \
--header "Accept: application/json" \
--header "Content-Type: application/json;ty=2" \
--data-raw '{
  "m2m:ae": {
    "rn": "FleetTracker",
    "api": "N-ACME-FleetTracker",
    "rr": false
  }
}'
{
  "m2m:ae": {
    "rn": "FleetTracker",
    "api": "N-ACME-FleetTracker",
    "rr": false,
    "ty": 2,
    "ri": "6a95994ae53217eee84f403d",
    "aei": "S-ft-munich-001",
    "cr": "S-ft-munich-001",
    "pi": "acme-iot",
    "ct": "20260831T151002,831000",
    "lt": "20260831T151002,831000"
  }
}

Step 4: Create an ACP for the new AE

Create acme-admin-acp as WeatherStation, which owns the acme-iot CSEBase after enforcement is enabled. Its pv grants all operations to both AEs. Its pvs allows only WeatherStation to manage the ACP itself or change the acpi attribute of resources governed by it. A successful creation returns HTTP 201 and X-M2M-RSC: 2001.

  • Copy & paste
  • Output
curl --location --request POST "$API_URL" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-M2M-Origin: S-ws-berlin-001" \
--header "X-M2M-RI: acp-example-4" \
--header "Accept: application/json" \
--header "Content-Type: application/json;ty=1" \
--data-raw '{
  "m2m:acp": {
    "rn": "acme-admin-acp",
    "pv": {
      "acr": [
        {
          "acor": [
            "S-ws-berlin-001",
            "S-ft-munich-001"
          ],
          "acop": 63
        }
      ]
    },
    "pvs": {
      "acr": [
        {
          "acor": [
            "S-ws-berlin-001"
          ],
          "acop": 63
        }
      ]
    }
  }
}'
{
  "m2m:acp": {
    "rn": "acme-admin-acp",
    "pv": {
      "acr": [
        {
          "acor": [
            "S-ws-berlin-001",
            "S-ft-munich-001"
          ],
          "acop": 63
        }
      ]
    },
    "pvs": {
      "acr": [
        {
          "acor": [
            "S-ws-berlin-001"
          ],
          "acop": 63
        }
      ]
    },
    "ty": 1,
    "cr": "S-ws-berlin-001",
    "ri": "6a959955e53217eee84f403e",
    "pi": "acme-iot",
    "ct": "20260831T151013,430000",
    "lt": "20260831T151013,430000"
  }
}

Step 5: Create a protected Container

Create the routes Container under FleetTracker and assign acme-admin-acp through acpi. The Container is created by S-ft-munich-001, and the referenced ACP grants that AE access to it. A successful creation returns HTTP 201 and X-M2M-RSC: 2001.

  • Copy & paste
  • Output
curl --location --request POST "$API_URL/FleetTracker" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-M2M-Origin: S-ft-munich-001" \
--header "X-M2M-RI: acp-example-5" \
--header "Accept: application/json" \
--header "Content-Type: application/json;ty=3" \
--data-raw '{
  "m2m:cnt": {
    "rn": "routes",
    "mni": 500,
    "acpi": [
      "acme-iot/acme-admin-acp"
    ]
  }
}'
{
  "m2m:cnt": {
    "rn": "routes",
    "mni": 500,
    "acpi": [
      "acme-iot/acme-admin-acp"
    ],
    "ty": 3,
    "st": 0,
    "cbs": 0,
    "cni": 0,
    "cr": "S-ft-munich-001",
    "ri": "6a95995ee53217eee84f403f",
    "pi": "6a95994ae53217eee84f403d",
    "ct": "20260831T151022,522000",
    "lt": "20260831T151022,522000"
  }
}

Step 6: Verify access as the new AE

Retrieve the protected Container as FleetTracker. The request succeeds because S-ft-munich-001 is included in an acor entry with RETRIEVE permission. A successful request returns HTTP 200 and X-M2M-RSC: 2000.

  • Copy & paste
  • Output
curl --location --request GET "$API_URL/FleetTracker/routes" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-M2M-Origin: S-ft-munich-001" \
--header "X-M2M-RI: acp-example-6" \
--header "Accept: application/json"
{
  "m2m:cnt": {
    "rn": "routes",
    "mni": 500,
    "acpi": [
      "acme-iot/acme-admin-acp"
    ],
    "ty": 3,
    "st": 0,
    "cbs": 0,
    "cni": 0,
    "cr": "S-ft-munich-001",
    "ri": "6a95995ee53217eee84f403f",
    "pi": "6a95994ae53217eee84f403d",
    "ct": "20260831T151022,522000",
    "lt": "20260831T151022,522000"
  }
}