Cumulocity IoT

Retrieve all applications: Get all the applications on your tenant. Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Retrieve a specific application: Get a specific application (by a given ID). Required roles: ROLE_APPLICATION_MANAGEMENT_READ OR current user has explicit access to the application.

Update a specific application: Update a specific application (by a given ID). Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Delete an application: Delete an application (by a given ID). This method is not supported by microservice applications. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN AND tenant is the owner of the application.

Copy an application: Copy an application (by a given ID). This method is not supported by microservice applications. A request to the clone resource creates a new application based on an already existing one. The properties are copied to the newly created application and the prefix clone is added to the properties name, key, and contextPath in order to be unique. If the target application is hosted and has an active version, the new application will have the active version with the same content. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Retrieve applications by name: Get the applications by name. Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Retrieve applications by tenant: Get the applications subscribed or associated with a particular tenant (by a given tenant ID). Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Retrieve applications by owner: Get all the applications associated with a particular tenant (by a given tenant ID). Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Retrieve applications by user: Get all the applications for a particular user (by a given username). Required roles: (ROLE_USER_MANAGEMENT_OWN_READ AND is the current user) OR (ROLE_USER_MANAGEMENT_READ AND ROLE_APPLICATION_MANAGEMENT_READ).

Retrieve a specific version of an application: Get the selected version of an application in your tenant. To select the version, use only the version or only the tag query parameter. Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Retrieve all versions of an application: Get all the versions of an application in your tenant. Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Delete a specific version of an application: Delete a specific version of an application in your tenant, by a given tag or version. Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

Replace an application version's tags: Replace the tags of a given application version in your tenant. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Retrieve all application attachments: Get all the application attachments. This method is not supported by microservice applications. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Retrieve a specific application attachment: Get a specific application attachment (by a given application ID and a given binary ID). This method is not supported by the microservice applications. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Delete a specific application attachment: Delete a specific application attachment (by a given application ID and a given binary ID). This method is not supported by the microservice applications. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN AND tenant is the owner of the application.

Retrieve the bootstrap user for a specific application: Get the bootstrap user for a specific application (by a given ID). This only works for microservice applications. Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Retrieve all measurements: Get all the measurements on your tenant, or a specific subset based on queries. In case of running range queries between an upper and lower boundaries (dateFrom -- dateTo), the oldest registered measurements are returned first. It is possible to change the order using the query parameter revert=true. For large measurement collections, querying older records without filters can be slow as the server must scan from the beginning of the input results set before returning the results. For scenarios where older measurements must be retrieved, it is recommended to use range queries based on the time stamp reported by a device. The scope of query can also be reduced by providing a source device.

Create a measurement with measurement: Create a measurement. A measurement must be associated with a source (managed object) identified by ID, type of measurement, and the time when it was measured by the device (for example, a thermometer). Each measurement fragment is an object (for example, c8y_Steam) containing the actual measurements as properties. The property name represents the name of the measurement (for example, Temperature) and it contains two properties:

• value - The value of the individual measurement. The maximum precision for floating point numbers is 64-bit IEEE 754. For integers, it is a 64-bit two's complement integer.
• unit - The unit of the measurement. For more information about the conversions of units, see system of units and naming conventions of fragments sections in the Cumulocity IoT Concepts guide.

Create measurements with measurement collection: Create multiple measurements at once by sending a measurements array containing all measurements to be created. The content type must be in the format: application/vnd.com.nsn.cumulocity.measurementcollection+json.

Required roles: ROLE_MEASUREMENT_ADMIN OR owner of the source OR MEASUREMENT_ADMIN permission on the source.

Remove measurement collections: Remove the measurement collections specified by query parameters. The delete requests are not synchronous. The response is returned before the delete request has been completed. This may happen especially when there are a lot of measurements to be deleted.

Required roles: ROLE_MEASUREMENT_ADMIN.

Retrieve a specific measurement: Get a specific measurement by a given ID. Tenants where time series is enabled, measurements can be searched using the query parameters. Required roles: ROLE_MEASUREMENT_READ or owner of the source or MEASUREMENT_READ permission on the source.

Remove a specific measurement: Delete a specific measurement by a given ID. Tenants where time series is enabled, measurements cannot be deleted by ID. You can remove expired time series measurements data from the Operational Store by query or using the retention rules. Required roles: ROLE_MEASUREMENT_ADMIN or owner of the source or MEASUREMENT_ADMIN permission on the source.

Retrieve a list of series and their values: Get a list of series (all or only those matching the specified names) and their values within a given period of a specific managed object (source). A series is any fragment in measurement that contains a value property. It is possible to retrieve aggregated results using the aggregationType parameter. If the aggregation is not specified, the result contains no more than 5000 values.

Required roles: ROLE_MEASUREMENT_READ or owner of the source or MEASUREMENT_READ permission on the source.

Retrieve all alarms: Get all the alarms on your tenant, or a specific subset based on queries.The results are sorted by the newest alarms first.

Query parameters: The query parameter withTotalPages works only when the user has the ROLE_ALARM_READ role, otherwise it is ignored. Required roles: The role ROLE_ALARM_READ is not required, but if a user has this role, all alarms on the tenant are returned. If a user has access to alarms through inventory roles, only those alarms are returned.

Required roles: ROLE_ALARM_ADMIN.

Create an alarm: Create an alarm. An alarm must be associated with a source (managed object) identified by ID. In general, each alarm consists of the following components:

• status indicating whether the alarm is Active, Acknowledged, or Cleared.

• time stamp indicating when the alarm is last updated.

• severity of the alarm such as Critical, Major, Minor, or Warning.

• history of changes to the event in the form of audit logs.

Alarm suppression - If the source device is in maintenance mode, the alarm is neither created nor reported to the Cumulocity IoT event processing engine. When sending a POST request to create a new alarm and if the source device is in maintenance mode, the self-link of the alarm is: "self": "https://<TENANT_DOMAIN>/alarm/alarms/null"

Alarm de-duplication - If an Active or Acknowledged alarm with the same source and type exists, no new alarm is created. Instead, the existing alarm is updated by incrementing the count property and the time property. Any other changes are ignored, and the alarm history is not updated. Alarms with status Cleared are not de-duplicated. The first occurrence of the alarm is recorded in the firstOccurrenceTime property.

Required roles: ROLE_ALARM_ADMIN OR owner of the source OR ALARM_ADMIN permission on the source.

Required roles: ROLE_ALARM_ADMIN.

Retrieve a specific alarm: Get a specific alarm by a given ID. Required roles: ROLE_ALARM_READ or owner of the source or ALARM_READ permission on the source.

Update a specific alarm: Update a specific alarm by a given ID. Only text, status, severity, and custom properties can be modified. Requests containing non-modifiable properties are rejected.

Required roles: ROLE_ALARM_ADMIN or owner of the source or ALARM_ADMIN permission on the source.

Retrieve the total number of alarms: Get the total number of active alarms on your tenant. Required roles: The role ROLE_ALARM_READ is not required, but if a user has this role, all alarms on the tenant are counted. Otherwise, inventory role permissions are used to count the alarms and the limit is 100.

Tenants API

Retrieve all subtenants: Get all the subtenants of the current tenant. Required roles: ROLE_TENANT_MANAGEMENT_READ.

Retrieve the current tenant: Get the information about the current tenant. Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.

Retrieve a specific tenant: Get a specific tenant (by a given ID). Required roles: ROLE_TENANT_MANAGEMENT_READ and the current tenant is its parent or is the management tenant.

Update a specific tenant: Update a specific tenant (by a given ID). Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_MANAGEMENT_UPDATE) and (the current tenant is its parent, and the current tenant is allowed to create subtenants) or is the management tenant.

Required roles: ROLE_TENANT_MANAGEMENT_ADMIN and is the management tenant.

Retrieve TFA settings of a specific tenant: Get the two-factor authentication settings of a specific tenant (by a given tenant ID). Required roles: (ROLE_TENANT_MANAGEMENT_READ) OR (ROLE_USER_MANAGEMENT_READ) and (the current tenant is its parent or is the management tenant or the current user belongs to the tenant) or the user belongs to the tenant and (ROLE_USER_MANAGEMENT_OWN_READ).

Retrieve subscribed applications: Get the subscribed applications (by a given tenant ID). Required roles (ROLE_TENANT_MANAGEMENT_READ OR ROLE_TENANT_ADMIN) and (the current tenant is its parent or is the management tenant).

Subscribe to an application: Subscribe a tenant (by a given ID) to an application. Required roles: (ROLE_APPLICATION_MANAGEMENT_ADMIN and is the application owner and is the current tenant) OR ((ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_UPDATE) and (the current tenant is its parent or is the management tenant)).

Unsubscribe from an application: Unsubscribe a tenant (by a given tenant ID) from an application (by a given application ID). Required roles: (ROLE_APPLICATION_MANAGEMENT_ADMIN and is the application owner and is the current tenant) or ((ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_MANAGEMENT_UPDATE) and (the current tenant is its parent or is the management tenant)).

Retrieve all stored certificates: Get all the trusted certificates of a specific tenant (by a given ID). Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN) OR (ROLE_TENANT_ADMIN) and (is the current tenant).

Add a new certificate: Add a new trusted certificate to a specific tenant (by a given ID) which can be further used by the devices to establish connections with the Cumulocity IoT platform. Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN) OR (ROLE_TENANT_ADMIN) and (is the current tenant).

Add multiple certificates: Add multiple trusted certificates to a specific tenant (by a given ID) which can be further used by the devices to establish connections with the Cumulocity IoT platform. Required roles (ROLE_TENANT_MANAGEMENT_ADMIN) OR (ROLE_TENANT_ADMIN) and (is the current tenant).

Retrieve a stored certificate: Get the data of a stored trusted certificate (by a given fingerprint) of a specific tenant (by a given ID). Required roles (ROLE_TENANT_MANAGEMENT_ADMIN) or (ROLE_TENANT_ADMIN) and (is the current tenant or is the management tenant).

Update a stored certificate: Update the data of a stored trusted certificate (by a given fingerprint) of a specific tenant (by a given ID). Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and (is the current tenant or is the management tenant).

Remove a stored certificate: Remove a stored trusted certificate (by a given fingerprint) from a specific tenant (by a given ID). Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and (is the current tenant or is the management tenant).

Provide the proof of possession for an already uploaded certificate: Provide the proof of possession for a specific uploaded certificate (by a given fingerprint) for a specific tenant (by a given ID). Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and is the current tenant.

Confirm an already uploaded certificate: Confirm an already uploaded certificate (by a given fingerprint) for a specific tenant (by a given ID). Required roles:(ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and is the management tenant.

Generate a verification code for the proof of possession operation for the given certificate: Generate a verification code for the proof of possession operation for the certificate (by a given fingerprint). (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and is the current tenant.

Retrieve monthly device statistics: Get the monthly device statistics from a specific tenant (by a given ID). Required roles: ROLE_TENANT_STATISTICS_READ.

Retrieve daily device statistics: Get the daily device statistics from a specific tenant (by a given ID). Required roles: ROLE_TENANT_STATISTICS_READ.

Retrieve statistics of the current tenant: Get the usage statistics of the current tenant. Required roles: ROLE_TENANT_STATISTICS_READ.

Retrieve a usage statistics summary: Get the usage statistics summary of a tenant.

Retrieve a summary of all usage statistics: Get a summary of all tenant usage statistics. Required roles: ROLE_TENANT_MANAGEMENT_READ.

Retrieve usage statistics files metadata: Get the usage statistics summary files report metadata. Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.

Generate a statistics file report: Generate a test statistics file report for a given time range. There are two types of statistics files:

• REAL: generated by the system on the first day of the month and includes statistics from the previous month to till date.

• TEST: generated by the user with a time range specified in the query parameters: dateFrom and dateTo.

Required roles: ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_MANAGEMENT_CREATE.

Retrieve a usage statistics file: Get a specific usage statistics file (by a given ID). Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.

Retrieve the latest usage statistics file: Get the latest usage statistics file with real data for a given month. There are two types of statistics files:

• REAL: generated by the system on the first day of the month and includes statistics from the previous month to till date.

• TEST - generated by the user with a time range specified in the query parameters, dateFrom and dateTo.

Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.

Retrieve all options: Get all the options available on the tenant. Required roles: ROLE_OPTION_MANAGEMENT_READ.

Create an option: Create an option on your tenant. Options are category-key-value tuples that store tenant configurations. Some categories of options allow the creation of new ones, while others are limited to predefined set of keys. Any option of any tenant can be defined as "non-editable" by the "management" tenant; once done, any PUT or DELETE requests made on that option by the tenant owner will result in a 403 error (Unauthorized).

Default option categories

access.control

alarm.type.mapping

Encrypted credentials

Adding a credentials. prefix to the key makes the value of the option encrypted. When the option is sent to a microservice, the credentials. prefix is removed and the value is decrypted. For example:

  		{ "category": "secrets",
  		  "key": "credentials.mykey",
  		  "value": "myvalue" 
  		}

In the example, the request contains an additional header Mykey: myvalue.

Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.

Retrieve all options by category: Get all the options (by a specified category) on your tenant. Required roles: ROLE_OPTION_MANAGEMENT_READ.

Update options by category: Update one or more options (by a specified category) on your tenant. Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.

Retrieve a specific option: Get a specific option (by a given category and key) on your tenant. Required roles: ROLE_OPTION_MANAGEMENT_READ.

Update a specific option: Update the value of a specific option (by a given category and key) on your tenant. Required roles: ROLE_OPTION_MANAGEMENT_ADMIN and the option is editable.

Remove a specific option: Remove a specific option (by a given category and key) on your tenant. Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.

Retrieve all login options: Get all the login options available in the tenant.

Create a login option: Create an authentication configuration on your tenant. Required roles: ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN.

Retrieve a specific login option: Get a specific login option in the tenant by the given type or ID. Required roles: ((ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN) or (ROLE_USER_MANAGEMENT_OWN_ADMIN or ROLE_USER_MANAGEMENT_CREATE) and tenant access to login option is not restricted by management tenant).

Update a specific login option: Update a specific login option in the tenant by a given type or ID. Required roles ((ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN) and tenant access to login option is not restricted by management tenant).

Delete a specific login option: Delete a specific login option in the tenant by a given type or ID. Required roles: ((ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN) and tenant access to login option is not restricted by management tenant).

Update a tenant's access to the login option: Update the tenant's access to the authentication configuration. Required roles: ROLE_TENANT_MANAGEMENT_ADMIN and is the management tenant.

Retrieve all system options: Get all the system options available on the tenant.

Retrieve a specific system option: Get a specific system option (by a given category and key) on your tenant. Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.

Retrieve the current user: Get the reference of the current user.Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.

Update the current user: Update the current user.Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Update the current user's password: Update the current user's password.

Required roles: ROLE_USER_MANAGEMENT_OWN_ADMIN.

Generate secret to set up TFA: Generates a secret code to create a QR code to set up the two-factor authentication functionality using a TFA app/service. For more information about the feature, see the User Guide in the Cumulocity IoT documentation for Two-factor authentication (TFA). Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.

Returns the activation state of the two-factor authentication feature: Retrieves the activation state of the two-factor authentication feature for the current user. Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.

Activates or deactivates the two-factor authentication feature: Activates or deactivates the two-factor authentication feature for the current user. For more information about the feature, see the User Guide in the Cumulocity IoT documentation for Two-factor authentication (TFA). Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.

Verify TFA code: Verifies the authentication code that the current user received from a TFA app/service and uploaded to the platform to gain access or enable the two-factor authentication feature. Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.

Retrieve all users for a specific tenant: Get all the users for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE.

Create a user for a specific tenant: Create a user for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND has access to roles, groups, device permissions and applications.

Retrieve a specific user for a specific tenant: Get a specific user (by a given user ID) for a specific tenant (by a given tenant ID). Users in the response are sorted by username in ascending order. Only objects that the user is allowed to see are returned to the user. The user password is never returned in a GET response. Authentication mechanism is provided by another interface.Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.

Update a specific user for a specific tenant: Update a specific user (by a given user ID) for a specific tenant (by a given tenant ID). Any change in user's role, device permission, and group details create corresponding audit records with type User and activity User updated. The audit records include information about the properties updated. When a user is updated with changed permissions or groups, a corresponding audit record is created with type User and activity User updated.Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND has access to device permissions and applications.

Delete a specific user for a specific tenant: Delete a specific user (by a given user ID) for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND not the current user.

Update a specific user's password of a specific tenant: Update a specific user's password (by a given user ID) of a specific tenant (by a given tenant ID). Changing the user's password creates a corresponding audit record of type "User" and activity "User updated” specifying that the password has been changed.

Required roles: ROLE_USER_MANAGEMENT_ADMIN to update root users in a user hierarchy or users that are not in any hierarchy. ROLE_USER_MANAGEMENT_ADMIN to update non-root users in a user hierarchy and whose parents have access to assigned roles, groups, device permissions and applications. ROLE_USER_MANAGEMENT_CREATE to update descendants of the current user in a user hierarchy and whose parents have access to assigned roles, groups, device permissions and applications.

Retrieve the TFA settings of a specific user: Get the two-factor authentication settings for the specified user. Required roles: ROLE_USER_MANAGEMENT_READ or(ROLE_USER_MANAGEMENT_CREATE and is parent of the user) or is the current user.

Retrieve a user by username in a specific tenant: Get a user by username in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.

Retrieve the users of a specific user group of a specific tenant: Get the users of a specific user group (by a given user group ID) of a specific tenant (by a given tenant ID). Required roles: ROLE_USER_MANAGEMENT_READ OR (ROLE_USER_MANAGEMENT_CREATE AND has access to the user group).

Add a user to a specific user group of a specific tenant: Add a user to a specific user group (by a given user group ID) of a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.

Remove a specific user from a specific user group of a specific tenant: Remove a specific user (by a given user ID) from a specific user group (by a given user group ID) of a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user.

Terminate a user's session: Ends a user's session after logging out. A user must enter valid credentials again to get access to the platform. The request is responsible for removing cookies from the browser and invalidating internal platform access tokens.

Retrieve all user groups of a specific tenant: Get all the user groups of a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE.

Create a user group for a specific tenant: Create a user group for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Retrieve a specific user group for a specific tenant: Get a specific user group (by a given user group ID) for a specific tenant (by a given tenant ID). Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user.

Update a specific user group for a specific tenant: Update a specific user group (by a given user group ID) for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Delete a specific user group for a specific tenant: Delete a specific user group (by a given user group ID) for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Retrieve a user group by group name for a specific tenant: Get a user group by group name for a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND has access to groups.

Get all user groups for specific user in a specific tenant: Retrieve all the user groups for a specific user (by a given user ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.

Retrieve all user roles: Get all the user roles.Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND has access to the user role.

Retrieve a user role by name: Get a user role by name.Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND the current user has access to the role with this name.

Retrieve all roles assigned to a specific user group in a specific tenant: Get all the roles assigned to a specific user group (by a given user group ID) in a specific tenant (by a given tenant ID). Required roles: ROLE_USER_MANAGEMENT_READ.

Assign a role to a specific user group in a specific tenant: Assign a role to a specific user group (by a given user group ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Unassign a specific role for a specific user group in a specific tenant: Unassign a specific role (given by a role ID) for a specific user group (by a given user group ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Assign a role to specific user in a specific tenant: Assign a role to a specific user (by a given user ID) in a specific tenant (by a given tenant ID). When a role is assigned to a user, a corresponding audit record is created with type User and activity User updated.Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.

Unassign a specific role from a specific user in a specific tenant: Unassign a specific role (by a given role ID) from a specific user (by a given user ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND has access to roles.

Retrieve all inventory roles: Get all the inventory roles.Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE.

Create an inventory role: Create an inventory role.Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Retrieve a specific inventory role: Get a specific inventory role (by a given ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND has access to the inventory role.

Update a specific inventory role: Update a specific inventory role (by a given ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Remove a specific inventory role: Remove a specific inventory role (by a given ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Retrieve all inventory roles assigned to a user: Get all the inventory roles assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is the parent of the user.

Assign an inventory role to a user: Assign an existing inventory role to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN AND (is not in user hierarchy OR is root in the user hierarchy) OR ROLE_USER_MANAGEMENT_ADMIN AND is in user hierarchy AND has parent access to inventory assignments OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user AND has current user access to inventory assignments AND has parent access to inventory assignments.

Retrieve a specific inventory role assigned to a user: Get a specific inventory role (by a given ID) assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID). Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is the parent of the user.

Update a specific inventory role assigned to a user: Update a specific inventory role (by a given ID) assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Remove a specific inventory role assigned to a user: Remove a specific inventory role (by a given ID) assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN AND (is not in user hierarchy OR is root in the user hierarchy) OR ROLE_USER_MANAGEMENT_ADMIN AND is in user hierarchy AND has parent access to inventory assignments OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user AND has current user access to inventory assignments AND has parent access to inventory assignments.

Returns all device permissions assignments: Get all device permissions assignments if the current user has READ permission. Required roles: ROLE_USER_MANAGEMENT_READ orROLE_USER_MANAGEMENT_CREATE

Updates the device permissions assignments: Update the device permissions assignments if the current user has ADMIN permission or CREATE permission and all device permissions. Required roles: ROLE_USER_MANAGEMENT_ADMINorROLE_USER_MANAGEMENT_CREATE.

Retrieve all audit records: Get all the audit records registered on your tenant, or a specific subset based on queries.

Create an audit record: Create an audit record. Required roles: ROLE_AUDIT_ADMIN OR ROLE_SYSTEM OR AUDIT_ADMIN permission on the resource.

Retrieve a specific audit record: Get a specific audit record by a given ID. Required roles: ROLE_AUDIT_READ OR AUDIT_READ permission on the source.

Realtime Notifications API

Responsive communication: The Real-time notification API enables responsive communication from Cumulocity IoT over restricted networks towards clients such as web browser and mobile devices. All clients subscribe to channels to receive messages. These channels are updated with the output of Operations. In addition, particular system channels are used for the initial handshake with clients, subscription to channels, removal from channels, and connection.

Retrieve all events: Gets all the events on your tenant. In case of running range queries between an upper and lower boundaries (dateFrom--dateTo or createdFrom--createdTo), the oldest registered measurements are returned first. It is possible to change the order using the query parameter revert=true. Required roles: ROLE_EVENT_READ.

Create an event: Create an event which is associated with a source (managed object) identified by an ID. In general, each event consists of:

• type to identify the nature of the event.

• time stamp to indicate when the event is last updated.

• description of the event.

• managed object which originated the event.

Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.

Remove event collections: Remove the event collections specified by query parameters. The delete requests are not synchronous. The response is returned before the delete request has been completed. This may happen especially when the deleted event has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested event is deleted after all associated data has been deleted.

Required roles: ROLE_EVENT_ADMIN.

Retrieve a specific event: Get a specific event by a given ID.Required roles: ROLE_EVENT_READ OR owner of the source OR EVENT_READ permission on the source.

Update a specific event: Update a specific event by a given ID. Only the text description and custom fragments of an event can be updated.Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.

Remove a specific event: Remove a specific event by a given ID.Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.

Retrieve the attached file of a specific event: Get the attached file (binary) of a specific event by a given ID.Required roles: ROLE_EVENT_READ OR EVENT_READ permission on the source.

Remove the attached file from a specific event: Remove the attached file (binary) from a specific event by a given ID. Required roles: ROLE_EVENT_ADMIN or owner of the source or EVENT_ADMIN permission on the source.

Retrieve all subscriptions: Get all the subscriptions on your tenant or a specific subset based on queries. Required roles: ROLE_NOTIFICATION_2_ADMIN.

Create a subscription: Create a new subscription, for example, a subscription that forwards measurements and events of a specific type for a given device. In general, each subscription may consist of the following components:

• managed object to which the subscription is associated.

• context under which the subscription is to be processed.

• name of the subscription.

• applicable filter criteria.

• option to only include specific custom fragments in the forwarded data.

Required roles: ROLE_NOTIFICATION_2_ADMIN.

Remove subscriptions by source: Remove subscriptions by source and context.

Required roles: ROLE_NOTIFICATION_2\_ADMIN.

Retrieve a specific subscription: Get a specific subscription by a given ID.Required roles: ROLE_NOTIFICATION_2_ADMIN.

Remove a specific subscription: Remove a specific subscription by a given ID.Required roles: ROLE_NOTIFICATION_2_ADMIN.

Create a notification token: Create a new JWT (JSON web token) access token that can be used to establish a successful WebSocket connection to read a sequence of notifications. In general, each request obtains an access token that consists of the following details:

• subscriber name that the client wants to be identified with.

• subscription name. This value must be associated with an already existing subscription (that is, the obtained token provides the ability to read notifications for the subscription that is specified here).

• token expiry duration.

Required roles: ROLE_NOTIFICATION_2_ADMIN.

Unsubscribe a subscriber: Unsubscribe a notification subscriber using the notification token. Once a subscription is made, notifications are stored until they are consumed by all subscribers who have previously connected to the subscription. For non-volatile subscriptions, this can lead to notifications being stored indefinitely if they are not consumed by the application. However, if a tenant is deleted, these notifications are removed. This can consume significant space in permanent storage for sources that generate notifications frequently. Therefore, unsubscribe a subscriber that is no longer active.

Retrieve all retention rules: Get all the retention rules on your tenant.Required roles: ROLE_RETENTION_RULE_READ.

Create a retention rule: Create a retention rule on your tenant.Required roles: ROLE_RETENTION_RULE_ADMIN.

Retrieve a retention rule: Get a specific retention rule by a given ID.Required roles: ROLE_RETENTION_RULE_READ.

Update a retention rule: Update a specific retention rule by a given ID. Required roles: ROLE_RETENTION_RULE_ADMIN AND (the rule is editable, OR it is the tenant management).

Remove a retention rule: Remove a specific retention rule by a given ID.Required roles: ROLE_RETENTION_RULE_ADMIN AND the rule is editable.

Retrieve URIs to collections of external IDs: Get the URIs and URI templates for associating external identifiers with unique identifiers.Required roles: ROLE_IDENTITY_READ.

Retrieve all external IDs of a specific managed object: Get all the external IDs of an existing managed object (identified by ID).Required roles: ROLE_IDENTITY_READ or owner of the resource or MANAGED_OBJECT_READ permission on the resource.

Create an external ID: Create an external ID for an existing managed object (identified by ID).Required roles: ROLE_IDENTITY_ADMIN or owner of the resource or MANAGED_OBJECT_ADMIN permission on the resource.

Retrieve a specific external ID: Get a specific external ID of a particular type.Required roles: ROLE_IDENTITY_READ or owner of the resource or MANAGED_OBJECT_READ permission on the resource.

Remove a specific external ID: Remove a specific external ID of a particular type.Required roles: ROLE_IDENTITY_ADMIN or owner of the resource or MANAGED_OBJECT_ADMIN permission on the resource.

Retrieve a list of operations: Get a list of operations.

Required roles: ROLE_DEVICE_CONTROL_READ.

Create an operation: Create an operation.Required roles: ROLE_DEVICE_CONTROL_ADMIN OR owner of the device OR ADMIN permissions on the device.

Delete a list of operations: Delete a list of operations. The DELETE method allows for deletion of operation collections.Required roles: ROLE_DEVICE_CONTROL_ADMIN.

Retrieve a specific operation: Get a specific operation (by a given ID).Required roles: ROLE_DEVICE_CONTROL_READ OR owner of the resource OR ADMIN permission on the device.

Update a specific operation status: Update a specific operation (by a given ID). You can only update its status.Required roles: ROLE_DEVICE_CONTROL_ADMIN OR owner of the resource OR ADMIN permission on the device.

Retrieve a list of bulk operations: Get a list of bulk operations.Required roles: ROLE_BULK_OPERATION_READ.

Create a bulk operation: Create a bulk operation.Required roles: ROLE_BULK_OPERATION_ADMIN.

Retrieve a specific bulk operation: Get a specific bulk operation (by a given ID).Required roles: ROLE_BULK_OPERATION_READ.

Update a specific bulk operation: Update a specific bulk operation (by a given ID).Required roles ROLE_BULK_OPERATION_ADMIN.

Delete a specific bulk operation: Delete a specific bulk operation (by a given ID).Required roles: ROLE_BULK_OPERATION_ADMIN.

Retrieve a list of new device requests: Get a list of new device requests. Required roles: ROLE_DEVICE_CONTROL_READ.

Create a new device request: Create a new device request.Required roles: ROLE_DEVICE_CONTROL_ADMIN.

Retrieve a specific new device request: Get a specific new device request (by a given ID).Required roles: ROLE_DEVICE_CONTROL_READ.

Update a specific new device request status: Update a specific new device request (by a given ID). You can only update its status.Required roles: ROLE_DEVICE_CONTROL_ADMIN.

Delete a specific new device request: Delete a specific new device request (by a given ID).Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Retrieve all managed objects: Get all the managed objects, for example, devices, assets, and so on, registered in your tenant, or a subset based on queries.

Create a managed object: Create a managed object, for example, a device with temperature measurements support or a binary switch. In general, each managed object may consist of:

• A unique identifier that references the object.

• The name of the object.

• The most specific type of the managed object.

• Time stamp showing the last update.

• Fragments with specific meanings, for example, c8y_IsDevice, c8y_SupportedOperations.

• Any additional custom fragments.

For example, you want to describe electric meters from different vendors. Depending on the make of the meter, one may have a relay and one may be capable to measure a single phase or three phases (for example, a three-phase electricity sensor). A fragment C8y_ThreePhaseElectricitySensor would identify such an electric meter. Device characteristics are identified by storing fragments for each of them.

Required roles: ROLE_INVENTORY_ADMIN OR ROLE_INVENTORY_CREATE.

Retrieve the total number of managed objects: Get the total number of managed objects, for example, devices, assets, and so on, registered in your tenant, or a subset based on queries.Required roles: ROLE_INVENTORY_READ is not required, but if the current user does not have this role, the response will contain the number of inventory objects accessible for the user.

Retrieve a specific managed object: Get a specific managed object (for example, device, group, template) by a given ID.Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Update a specific managed object: Update a specific managed object (for example, device) by a given ID. For example, if you want to specify that your managed object is a device, you must add the fragment c8y_IsDevice.Required roles: ROLE_INVENTORY_ADMIN OR owner of the source OR MANAGE_OBJECT_ADMIN permission on the source.

Required roles: ROLE_INVENTORY_ADMIN OR owner of the source OR MANAGE_OBJECT_ADMIN permission on the source.

Retrieve the latest availability date of a specific managed object: Get the date when a specific managed object (by a given ID) sent the last message to Cumulocity IoT. Required roles: ROLE_INVENTORY_READ.

Retrieve all supported measurement fragments of a specific managed object: Get all the measurement types of a specific managed object by a given ID. Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Retrieve all supported measurement fragments and series of a specific managed object: Get all the supported measurement fragments and series of a specific managed object by a given ID. Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Retrieve the username and state of a specific managed object: Get the device owner's username and state (enabled or disabled) of a specific managed object (by a given ID). Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Update the user's details of a specific managed object: Update the device owner's state (enabled or disabled) of a specific managed object (by a given ID). Required roles: ROLE_INVENTORY_ADMIN OR owner of the source OR MANAGE_OBJECT_ADMIN permission on the source.

Search for stored files: Retrieve metadata information about stored files. Search for files by query parameters. This will not download the files.

Retrieve a stored file: Get a stored file (managed object) by a given ID. Required roles: ROLE_INVENTORY_READ OR owner of the resource OR MANAGE_OBJECT_READ permission on the resource.

Remove a stored file: Remove a managed object and its stored file by a given ID.Required roles: ROLE_INVENTORY_ADMIN OR owner of the resource OR MANAGE_OBJECT_ADMIN permission on the resource.

Retrieve all child additions of a specific managed object: Get all child additions of a specific managed object by a given ID, or a subset based on queries. Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Assign a managed object as child addition: Assign a managed object as child. The possible ways to assign child objects are:

• Assign an existing managed object (by a given child ID) as child addition of another managed object (by a given ID).

• Assign multiple existing managed objects (by given child IDs) as child additions of another managed object (by a given ID).

• Create a managed object in the inventory and assign it as a child addition to another managed object (by a given ID).

Required roles: ROLE_INVENTORY_ADMIN OR ((owner of the source OR MANAGE_OBJECT_ADMIN permission on the source) AND (owner of the child OR MANAGE_OBJECT_ADMIN permission on the child)).

Remove specific child additions from its parent: Remove specific child additions (by given child IDs) from its parent (by a given ID). Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Retrieve a specific child addition of a specific managed object: Get a specific child addition (by a given child ID) of a specific managed object (by a given ID). Required roles: ROLE_INVENTORY_READ OR MANAGE_OBJECT_READ permission on the source (parent).

Remove a specific child addition from its parent: Remove a specific child addition (by a given child ID) from its parent (by a given ID). Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Retrieve all child assets of a specific managed object: Get all child assets of a specific managed object by a given ID, or a subset based on queries. Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Assign a managed object as child asset: Assign a managed object as child asset. The possible ways to assign child objects are:

• Assign an existing managed object (by a given child ID) as child asset of another managed object (by a given ID).

• Assign multiple existing managed objects (by given child IDs) as child assets of another managed object (by a given ID).

• Create a managed object in the inventory and assign it as a child asset to another managed object (by a given ID).

Required roles: ROLE_INVENTORY_ADMIN OR ((owner of the source OR MANAGE_OBJECT_ADMIN permission on the source) AND (owner of the child OR MANAGE_OBJECT_ADMIN permission on the child)).

Remove specific child assets from its parent: Remove specific child assets (by given child IDs) from its parent (by a given ID). Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Retrieve a specific child asset of a specific managed object: Get a specific child asset (by a given child ID) of a specific managed object (by a given ID). Required roles: ROLE_INVENTORY_READ OR MANAGE_OBJECT_READ permission on the source (parent).

Remove a specific child asset from its parent: Remove a specific child asset (by a given child ID) from its parent (by a given ID). Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Retrieve all child devices of a specific managed object: Get all child devices of a specific managed object by a given ID, or a subset based on queries. Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.

Assign a managed object as child device: Assign a managed object as child device. The possible ways to assign child objects are:

• Assign an existing managed object (by a given child ID) as child device of another managed object (by a given ID).

• Assign multiple existing managed objects (by given child IDs) as child devices of another managed object (by a given ID).

• Create a managed object in the inventory and assign it as a child device to another managed object (by a given ID).

Required roles: ROLE_INVENTORY_ADMIN OR (owner of the source OR MANAGE_OBJECT_ADMIN permission on the source) AND (owner of the child OR MANAGE_OBJECT_ADMIN permission on the child).

Remove specific child devices from its parent: Remove specific child devices (by given child IDs) from its parent (by a given ID). Required roles ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Retrieve a specific child device of a specific managed object: Get a specific child device (by a given child ID) of a specific managed object (by a given ID). Required roles: ROLE_INVENTORY_READ OR MANAGE_OBJECT_READ permission on the source (parent).

Remove a specific child device from its parent: Remove a specific child device (by a given child ID) from its parent (by a given ID). Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Is it possible to subscribe to smart groups of devices?

No, only subscriptions to normal groups are supported.

Is it possible to subscribe events for all devices on the Cumulocity IoT tenant?

This is not allowed due to performance limitations. The alternative is to create a group in Cumulocity IoT with the devices you want to monitor and subscribe to this group.

How can I subscribe to a managed object that is neither a device nor a group?

You can select Specific Device and then enter manually the ID of the managed object in the field.