Cumulocity Device Permissions API

openapi: 3.2.0
info:
  version: Latest
  title: Cumulocity Device Permissions API
  x-logo:
    url: https://www.cumulocity.com/docs/images/logo-platform.svg
    backgroundColor: '#F8F8F8'
    altText: Cumulocity
    href: https://www.cumulocity.com/api
  description: '# REST implementation


    This section describes the aspects common to all REST-based interfaces of Cumulocity. The interfaces are based on the Hypertext Transfer Protocol 1.1 using HTTPS. ## HTTP usage


    ### Application management


    Cumulocity uses a so-called "application key" to distinguish requests coming from devices and traffic from applications. If you write an application, pass the following header as part of all requests:


    ```markup

    X-Cumulocity-Application-Key:

    ```


    For example, if you registered your application in the Cumulocity Administration application with the key "myapp", your requests should contain the header:


    ```markup

    X-Cumulocity-Application-Key: myapp

    ```


    This makes your application subscribable and billable. If you implement a device, do not pass the key. > **ⓘ Info:** Make sure that you pass the key in **all** requests coming from an application. If you leave out the key,

    > the request will be considered as a device request, and the corresponding device will be marked as "available". ### Limited HTTP clients


    If you use an HTTP client that can only perform GET and POST methods in HTTP, you can emulate the other methods through an additional "X-HTTP-METHOD" header. Simply issue a POST request and add the header, specifying the actual REST method to be executed. For example, to emulate the "PUT" (modify) method, you can use:


    ```http

    POST ... X-HTTP-METHOD: PUT

    ```


    ### Processing mode


    Every update request (PUT, POST, DELETE) executes with a so-called *processing mode*. The processing modes are as follows:


    |Processing mode|Description|

    |---|---|

    |PERSISTENT (default)|Stores data in the Cumulocity database and sends data to the Streaming Analytics engine. Afterwards, Cumulocity returns the result of the request. This is the default mode.|

    |TRANSIENT|Sends data to the Streaming Analytics engine and immediately returns the results asynchronously but does not store data in Cumulocity’s database. This mode saves storage and processing costs and is useful for example when tracking devices in real time without requiring data to be stored.|

    |QUIESCENT|Behaves similar to the persistent mode with the exception that no real-time notifications will be sent.|

    |CEP|Behaves like the transient mode with the exception that no real-time notifications are sent.|


    To explicitly control the processing mode of an update request, you can use the "X-Cumulocity-Processing-Mode" header with a value of either "PERSISTENT", "TRANSIENT", "QUIESCENT" or "CEP":


    ```markup

    X-Cumulocity-Processing-Mode: PERSISTENT

    ```


    > **ⓘ Info:** Events are always delivered to CEP/Apama for all processing modes. This is independent from real-time notifications. ### Authorization


    All requests issued to Cumulocity are subject to authorization. To determine the required permissions, see the "Required role" entries for the individual requests. To learn more about the different permissions and the concept of ownership in Cumulocity, see Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions in the Cumulocity user documentation. > **⚠️ Important:** In the Cumulocity API, each granular permission is identified by a unique “permission” string, which is prefixed with ROLE_ (for example, ROLE_ALARM_READ, ROLE_INVENTORY_ADMIN). Therefore, permissions are frequently referred to as “roles” throughout the API as well as in the configuration files. For example, the microservice manifest includes a requiredRoles field, which actually expects a permission string. See also the Glossary of the Cumulocity user documentation for the usage of the terms “permission” and “role” in the Cumulocity context. ### Media types


    Each type of data is associated with an own media type. The general format of media types is:


    ```markup

    application/vnd.com.nsn.cumulocity.+json;ver=;charset=UTF-8

    ```


    Each media type contains a parameter `ver` indicating the version of the type.'
servers:
- description: Cumulocity tenant
  url: https://<TENANT_DOMAIN>
security:
- Basic: []
- OAI-Secure: []
- SSO: []
- JWT-IAM: []
tags:


# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/openapi/cumulocity-device-permissions-api-openapi.yml