Tenants
The tenant interface consists of the following parts:
Resource | Description |
---|---|
Tenant collection | Retrieves tenants Accessible by URL /tenant/tenants |
Tenant | Represents an individual tenant that can be viewed Accessible by URL /tenant/tenants/<tenantId> |
Application reference collection | Retrieves applications Accessible by URL /tenant/tenants/<tenantId>/applications |
Application reference | Represents an individual application reference that can be viewed Accessible by URL /tenant/tenants/<tenantId>/applications/<applicationId> |
Option collection | Enables creating new options and viewing existing ones Accessible by URL /tenant/options |
Option | Represents an individual option that can be viewed and modified Accessible by URL /tenant/options/<optionCategory>/<optionKey> |
Usage statistics | Returns information on the request load and database usage of tenants |
Current tenant | Represents user data for the current logged service user |
Trusted certificates | Represents certificates which the tenant trusts Accessible by URL /tenant/tenants/<tenantId>/trusted-certificates |
Important: For all PUT/POST requests, the “Accept” header shall be provided, otherwise an empty response body will be returned.
Tenant ID and tenant domain
The tenant ID is a unique identifier across all tenants in Cumulocity IoT, e.g. t07007007. It cannot be changed after tenant creation.
It is recommended to use auto-generated tenant IDs, which follow the format t<number>
, for all tenant types.
The location where a tenant can be accessed is called tenant domain, e.g. mytenant.cumulocity.com. It needs to be unique across all tenants and it can be changed after tenant creation.
The tenant domain may contain lowercase letters, digits or hyphens. It must start with a letter; hyphens are only allowed in the middle; minimum is 2 characters. Note that the usage of underscore characters is deprecated but still possible for backward compatibility reasons.
In general, the tenant domain should be used for communication if it is known.
Important: For support user access, the tenant ID must be used and not the tenant domain.
See Tenant > Current tenant for information on how to retrieve the tenant ID and domain of the current tenant via the API.
In the UI, the tenant ID is displayed in the user dropdown menu, see Getting started > User options and settings in the User guide.
Tenant collection
TenantCollection [application/vnd.com.nsn.cumulocity.tenantCollection+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
tenants | array | 0..n | List of tenants, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of tenants. |
next | string | 0..1 | A URI linking to a potential next page of tenants. |
GET a representation of a Tenant Collection.
Response body: TenantCollection
Required role: ROLE_TENANT_MANAGEMENT_READ
Example Request: Get tenants as sample_tenant.
GET /tenant/tenants
Host: ...
Authorization: Basic ...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantcollection+json;ver=...
Content-Length: ...
{
"statistics": {
"currentPage": 1,
"pageSize": 5,
"totalPages": 1
},
"self": "<<Collection URL>>",
"tenants": [
{
"adminName": "admin",
"allowCreateTenants": false,
"storageLimitPerDevice": 10485760,
"applications": {
"references": [],
"self":"<<ApplicationCollection of This Tenant URL>>",
},
"company": "sample_company",
"domain": "sample_domain.com",
"id": "sample_tenant",
"ownedApplications": {
"references": [
{
"application": {
"availability": "PRIVATE",
"id": "5",
"key": "<<hashed value>>",
"name": "sample_private_application",
"owner": {
"self":"<<Application Owner Tenant URL>>",
"tenant": {
"id": "sample_tenant"
}
},
"self":"<<Application 5 URL>>",
"type": "EXTERNAL"
},
"self":"<<This Tenant Application 5 URL>>",
},
...
],
"self":"<<ApplicationCollection of This Tenant URL>>",
},
"self":"<<This Tenant URL>>",
"parent": "parentTenant",
"status": "ACTIVE"
},
{
"applications": {
"references": [],
"self": "<<ApplicationCollection of This Tenant URL>>",
},
"company": "sample_company",
"domain": "sample_domain.com",
"id": "next_sample_tenant",
"ownedApplications": {
"references": [
{
"application": {
"availability": "MARKET",
"id": "6",
"key": "<<hashed value>>",
"name": "market_application",
"owner": {
"self":"<<Application Owner Tenant URL>>",
"tenant": {
"id": "next_sample_tenant"
}
},
"self":"<<Application 6 URL>>",
"type": "EXTERNAL"
},
"self":"<<This Tenant Application 6 URL>>",
}
],
"self":"<<ApplicationCollection of This Tenant URL>>",
},
"self":"<<This Tenant URL>>",
},
...
]
}
POST - Create a new Tenant
Request body: Tenant
Response body: Tenant
Required role: ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_CREATE
Example request:
POST /tenant/tenants
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver...
{
"id" : "sample_tenant",
"company" : "sample_company",
"domain" : "sample_domain.com",
"contactName" : "Mr. Doe",
"contactPhone" : "0123-4567829",
"adminEmail" : "john.doe@sample_domain.com",
"adminName" : "firstAdmin",
"adminPass" : "myPassword",
"customProperties" : {"referenceId":"1234567890"},
"sendPasswordResetEmail": true
}
Example Response:
HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
Location: <<URL of new tenant>>
{
"id" : "sample_tenant",
"allowCreateTenants": false,
"self" : "<<URL of new tenant>>",
"company" : "sample_company",
"domain" : "tenant_nsn.com",
"contactName" : "Mr. Doe",
"contactPhone" : "0123-4567829",
"status" : "ACTIVE",
"adminName" : "firstAdmin",
"parent": "parentTenant",
"customProperties" : {"referenceId":"1234567890"}
}
The following table lists the fields of a tenant creation requests, along with their length constraints. The fragments domain
and company
always have to be provided.
Field | Description | Max. Length | Required |
---|---|---|---|
company | Company name | 256 | Yes |
domain | Domain name to be used for the tenant | 256 | Yes |
id | The tenant ID. Will be auto-generated if not present. | 32 | No |
adminName | Username of the tenant administrator | 50 | No |
adminPass | Password of the tenant administrator | 32 | No |
adminEmail | Email address of the administrator | 254 | No |
contactName | A contact name, for example an administrator, of the tenant | No | |
contact_phone | 20 | An international contact phone number | No |
customProperties | A set of custom properties of the agent | No |
The naming convention for tenant ID is:
- only lowercase letters, digits, hyphen and underscore is allowed
- MUST start with a letter
- hyphen and underscore are only allowed in the middle
- MUST have a minimum length of two characters
Tenant
Tenant [application/vnd.com.nsn.cumulocity.tenant+json]
Name | Type | Occurs | Description | Visibility |
---|---|---|---|---|
self | string | 0..1 | A URI linking to this resource. | Public |
id | string: max length="32” | 1 | Unique identifier of the tenant. | Public |
status | string | 1 | Status of the tenant. Possible values: ACTIVE, SUSPENDED | Private |
adminName | string: max length = “50” | 1 | Administrator user name. Whitespaces, slashes, +$: characters not allowed. | Private |
adminEmail | string | 1 | Administrator Email. | Private |
allowCreateTenants | boolean | 1 | Can this tenant create its own tenants. | Private |
storageLimitPerDevice | int | 1 | Storage quota per device the user has. | Private |
adminPassword | string | 1 | Administrator Password. | Private |
sendPasswordResetEmail | boolean | 1 | Enable password reset. | Private |
domain | string: max length = “256” | 1 | URL of tenants domain. | Public |
company | string: max length = “256” | 1 | Tenants company name. | Public |
contactName | string: max length = “30” | 1 | Contact person name. | Public |
contactPhone | string: max length= “20” | 1 | Contact person phone number. | Public |
applications | ApplicationReferenceCollection | 1 | Collection of tenant subscribed, applications. | Private |
ownedApplications | ApplicationReferenceCollection | 1 | Collection of tenant owned, applications. | Public - only applications with availability MARKET |
customProperties | Object | 1 | Keeps a list of custom properties. | optional |
parent | string | 1 | Name of parent tenant, the creator of this tenant. | Public |
Current tenant
Content-Type: application/vnd.com.nsn.cumulocity.currenttenant+json
Field Name | Type | Occurs | Description |
---|---|---|---|
name | string | 1 | Tenant. |
domainName | string | 1 | Domain name. |
allowCreateTenants | boolean | 1 | Flag indicating if a tenant can create subtenants. |
GET the current tenant details
Request for the currently logged service user’s tenant.
Required role: ROLE_USER_MANAGEMENT_OWN_READ, or ROLE_SYSTEM
ResponseBody: CurrentTenant
GET /tenant/currentTenant
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.nsn.cumulocity.currenttenant+json;;ver=...
Example response:
{
"allowCreateTenants": true,
"customProperties": {},
"domainName": "...",
"name": "..."
}
Note that in this case the response property "name"
is the actual tenant ID.
GET a representation of a Tenant.
Response body: Tenant
Required role: ROLE_TENANT_MANAGEMENT_READ
Example Request: Get single tenant.
GET /tenant/tenants/<<tenantId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
{
"adminName": "admin",
"applications": {
"references": [],
"self":"<<ApplicationCollection of This Tenant URL>>",
},
"company": "sample_company",
"domain": "sample_domain.com",
"allowCreateTenants": false,
"storageLimitPerDevice": 10485760,
"id": "sample_tenant",
"ownedApplications": {
"references": [
{
"application": {
"availability": "PRIVATE",
"id": "5",
"key": "<<hashed value>>",
"name": "sample_private_application",
"owner": {
"self":"<<Application Owner Tenant URL>>",
"tenant": {
"id": "sample_tenant"
}
},
"self":"<<Application 5 URL>>",
"type": "EXTERNAL"
},
"self":"<<This Tenant Application 5 URL>>",
},
...
],
"self":"<<ApplicationCollection of This Tenant URL>>",
},
"self":"<<This Tenant URL>>",
"parent": "parentTenant",
"status": "ACTIVE"
}
PUT - Update an existing tenant.
Request body: Tenant
Response body: Tenant
Required role: ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_UPDATE
Example Request :
PUT /tenant/tenants/<<tenantId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Accept: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
{
"adminName" : "newAdmin"
}
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
{
"id": "sample_tenant",
"self":"<<ApplicationCollection of This Tenant URL>>",
"company": "sample_company",
"domain": "sample_domain.com",
"status": "ACTIVE",
"self":"<<This Tenant URL>>",
"allowCreateTenants": false,
"storageLimitPerDevice": 10485760,
"parent": "parentTenant",
"ownedApplications": {
"references": [
{
"application": {
"availability": "PRIVATE",
"id": "5",
"key": "<<hashed value>>",
"name": "sample_private_application",
"owner": {
"self":"<<Application Owner Tenant URL>>",
"tenant": {
"id": "sample_tenant"
}
},
"self":"<<Application 5 URL>>",
"type": "EXTERNAL"
},
"self":"<<This Tenant Application 5 URL>>",
},
...
],
},
"adminName" : "newAdmin"
}
Note that updating adminPass and adminEmail updates these settings in the admin user of the tenant. Updating adminName has no effect.
DELETE a representation of a Tenant.
Important: Deleting a subtenant cannot be reverted. For security reasons, it is therefore only available in the management tenant. You cannot delete tenants from any tenant but the management tenant.
Administrators in Enterprise Tenants are only allowed to suspend active subtenants, but not to delete them.
Request body: N/A
Response body: N/A
Required role: ROLE_TENANT_MANAGEMENT_ADMIN
Example request:
DELETE /tenant/tenants/<<tenantId>>
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Example response:
HTTP/1.1 204 NO CONTENT
Application reference collection
ApplicationReferenceCollection [application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json].
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
references | array | 0..n | List of Options, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of options. |
next | string | 0..1 | A URI linking to a potential next page of options. |
POST application to tenant applications
Example Request: Adds application reference to tenant’s applications.
Required role: ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_UPDATE
POST /tenant/tenants/<<tenantId>>/applications
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.applicationreference+json;ver=...
{
"application":{"self":"<<Application URL>>"}
}
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationreference+json;ver=...
Content-Length: ...
{
"application":{"self":"<<Application URL>>", "id":...}
}
Info: A POST request for adding a microservice application to the tenant’s applications is not synchronous with the creation of assets on the container cluster. An attempt to invoke the microservice immediately after the creation of the subscription might result in an error because the name of the service is yet not known in the cluster.
GET a representation of a ApplicationReferenceCollection.
Response body: ApplicationReferenceCollection
Required role: ROLE_TENANT_MANAGEMENT_READ
Example Request: Get Application reference collection.
GET /tenant/tenants/<<tenantId>>/applications
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.applicationreferencecollection+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationreferencecollection+json;ver=...
Content-Length: ...
{
"self" : "<<Collection URL>>",
"references": [
{
"application": {
"availability": "PRIVATE",
"id": "5",
"key": "<<hashed value>>",
"name": "sample_private_application",
"owner": {
"self":"<<Application Owner Tenant URL>>",
"tenant": {
"id": "sample_tenant"
}
},
"self":"<<Application 5 URL>>",
"type": "EXTERNAL"
},
"self":"<<This Tenant Application 5 URL>>",
},
...
],
"statistics" : {
"totalPages" : 1,
"pageSize" : 5,
"currentPage" : 1
},
"next" : "...",
"prev" : "..."
}
Application reference
ApplicationReference [application/vnd.com.nsn.cumulocity.applicationReference+json].
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
reference | Application | 0..n | The Application being referenced. |
DELETE application reference from tenant’s applications.
Response body: ApplicationReference
Required role: ROLE_TENANT_MANAGEMENT_ADMIN
Example Request: Delete reference.
DELETE /tenant/tenants/<<tenantId>>/applications/<<applicationId>>
Host: ...
Authorization: Basic ...
Example Response :
HTTP/1.1 204 NO CONTENT
Option collection
OptionCollection [application/vnd.com.nsn.cumulocity.optionCollection+json].
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
options | array | 0..n | List of Options, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of options. |
next | string | 0..1 | A URI linking to a potential next page of options. |
GET a representation of a OptionCollection.
Response body: OptionCollection
Required role: ROLE_OPTION_MANAGEMENT_READ
Example Request: Get options.
GET /tenant/options
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Content-Length: ...
{
"self" : "<<Collection URL>>",
"options": [
{
"category": "access.control",
"key": "allow.origin",
"self": "<<Option access.control.allow.origin URL>>",
"value": "*"
},
...
],
"statistics" : {
"totalPages" : 1,
"pageSize" : 5,
"currentPage" : 1
},
"next" : "...",
"prev" : "..."
}
POST a representation of a Option.
Request body: Option
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_ADMIN
Example Request: Post option.
POST /tenant/options
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
"category" : "alarm.type.mapping",
"key": "temp_too_high",
"value": "CRITICAL|temperature too high"
}
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Content-Length: ...
{
"self" : "<<Option alarm.type.mapping.temp_too_high URL>>"
"category" : "alarm.type.mapping",
"key": "temp_too_high",
"value": "CRITICAL|temperature too high"
}
Option
Options are category-key-value tuples, storing tenant configuration. Some categories of options allow creation of new one, other are limited to predefined set of keys.
Any option of any tenant can be defined as “non-editable” by “management” tenant. Afterwards, any PUT or DELETE requests made on that option by the owner tenant, will result in 403 error (Unauthorized).
Default Options
Category | Key | Default value | Only predefined | Description |
---|---|---|---|---|
access.control | allow.origin | * | yes | Comma separated list of domains allowed for execution of CORS. Wildcards are allowed (e.g. *.cumuclocity.com) |
alarm.type.mapping | <<alarmType>> | no | Overrides severity and alarm text for the alarm with type “<<alarmType>>". Severity and text are specified as “<<alarmSeverity>>|<<alarmText>>". If either part of the text is empty, the value will not be overridden. If severity is “NONE”, the alarm will be suppressed. |
Option [application/vnd.com.nsn.cumulocity.option+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 0..1 | A URI linking to this resource. |
category | string | 1 | Category of option. |
key | string | 1 | Key of option. |
value | string | 1 | Value of option. |
Info: Adding “credentials.” prefix to the key will make the value of the option to be encrypted. Additionally, when the option is being sent to the microservice, the “credentials.” prefix is removed and the value is decrypted. For example:
{
"category": "c8y-tutorial-7",
"key": "credentials.mykey",
"value": "myvalue"
}
In the request now there will be an additional header:
"Mykey": "myvalue"
GET a representation of a Option.
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_READ Example Request: Get single option.
GET /tenant/options/<<category>>/<<key>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Content-Length: ...
{
"category": "access.control",
"key": "allow.origin",
"self": "<<Option access.control.allow.origin URL>>",
"value": "*"
}
PUT - Update a Option.
Request body: Option
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_ADMIN Example Request: Update access.control.allow.origin option.
PUT /tenant/options/<<category>>/<<key>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
"value": "http://developer.cumulocity.com"
}
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Content-Length: ...
{
"category": "access.control",
"key": "allow.origin",
"self": "<<Option access.control.allow.origin URL>>",
"value": "http://developer.cumulocity.com"
}
PUT - Update multiple options in provided category
Request body: Option
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_ADMIN Example Request: Update options in provided category.
PUT /tenant/options/<<category>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
"key1": "value1",
"key2": "value2",
"key3": "value3",
"key4": "value4"
}
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
GET Options from provided category.
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_READ Example Request: Get options from given category.
GET /tenant/options/<<category>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Content-Length: ...
{
"key1": "value1"
"key2": "value2",
"key3": "value3",
"key4": "value4",
}
PUT - Define option editability.
Request body: Option
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_ADMIN, Required tenant: management Example Request: Update access.control.allow.origin option.
PUT /tenant/options/<<category>>/<<key>>/editable
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
"editable": "false"
}
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Content-Length: ...
{
"category": "access.control",
"key": "allow.origin",
"self": "<<Option access.control.allow.origin URL>>",
"value": "http://developer.cumulocity.com"
}
System options
This endpoint provides a set of read-only properties pre-defined in platform configuration. The response format is exactly the same as for OptionCollection.
Response body: OptionCollection
Required role: ROLE_OPTION_MANAGEMENT_READ
Example Request: Get system options.
GET /tenant/system/options
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Content-Length: ...
{
"options": [
{
"category": "access.control",
"key": "allow.origin",
"value": "*"
},
...
],
}
It is also poss ible to query a single system option by passing category
and id
in the URL path:
Response body: Option
Required role: ROLE_OPTION_MANAGEMENT_READ Example Request: Get single option.
GET /tenant/system/option/<<category>>/<<id>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optioncollection+json;ver=...
Content-Length: ...
{
"category": "access.control",
"key": "allow.origin",
"value": "*"
}
Login options
The following endpoint shows which login options are configured for a tenant.
Info: If OAuth external is the only login option shown in the response, the user will be automatically redirected to the SSO login screen.
GET login options of a tenant.
Response body: loginOptions
Required role: ROLE_TENANT_MANAGEMENT_READ
Example Request: Get loginOptions
GET <<tenantUrl>>/tenant/loginOptions
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.loginoptioncollection+json;charset=UTF-8;ver=...
Example Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.loginoptioncollection+json;charset=UTF-8;ver=...
Content-Length: ...
{
"self": "<<tenantUrl>>/tenant/loginOptions/",
"loginOptions": [
{
"userManagementSource": "INTERNAL",
"initRequest": "<<tenantUrl>>/tenant/oauth?tenant_id=<<tenantId>>",
"enforceStrength": "false",
"self": "<<tenantUrl>>/tenant/loginOptions/<<loginOptionsId>>",
"id": "<<loginOptionsId>>",
"grantType": "PASSWORD",
"visibleOnLoginPage": true,
"type": "OAUTH2_INTERNAL",
"tfaStrategy": "SMS"
}
]
}
Tenant usage statistics
UsageStatistics
Name | Type | Occurs | Description |
---|---|---|---|
day | datetime | 1 | Date of statistics. |
deviceCount | int | 1 | Number of devices in the tenant (c8y_IsDevice). Latest value for a queried period. |
deviceEndpointCount | int | 1 | Number of devices which do not have child devices (leaf devices). Latest value for a queried period. |
deviceRequestCount | int | 1 | Number of requests that were issued only by devices against the tenant. Sum of all issued requests during the queried period. |
deviceWithChildrenCount | int | 1 | Number of devices with all children. Latest value for a queried period. |
requestCount | int | 1 | Number of requests that were issued against the tenant. Sum of all issued requests during the queried period. |
storageSize | int | 1 | Database storage in use by the tenant, in bytes. Latest value for a queried period. |
subscribedApplications | array | 1 | Names of tenant subscribed applications. Latest value for a queried period. |
“requestCount” - the following requests are not included in the counter:
- internal SmartREST requests used to resolve templates
- internal SLA monitoring requests
- calls to any “/health” endpoint
- device bootstrap process requests related to configuring and retrieving device credentials
- Microservice SDK internal calls for applications and subscriptions - “/currentApplication”
“deviceRequestCount” - in addition to the exceptions already listed for “requestCount” the following requests are not included in the counter:
- requests to /user, /tenant and /application API’s
- application related requests (with “X-Cumulocity-Application-Key” header)
Note:
- “requestCount” and “deviceRequestCount” are updated every 5 minutes.
- “deviceCount”, “deviceEndpointCount”, “deviceWithChildrenCount”, “storageSize” and “subscribedApplications” are updated only three times a day starting at 8:57, 16:57 and 23:57.
- “storageSize” is affected by your retention rules. It is also affected by the regularly running database optimization functions running in Cumulocity IoT. If the size decreases, it does not necessarily mean that data was deleted.
- Days are counted according to server timezone, so be aware that the tenant usage statistics displaying/filtering may not work correctly when the client is not in the same timezone as the server. However, it is possible to send a request with a time range (
dateFrom
anddateTo
) in zoned format (e.g.2020-10-26T03:00:00%2B01:00
).
Request counting in SmartREST and MQTT:
- SmartREST:
Each row in a SmartREST request is transformed into a separate HTTP request. For example, if one SmartREST request contains 10 rows, then 10 separate calls are executed, meaning that request count is increased by 10. - MQTT:
Each row/line counts as a separate request. Creating custom template counts as a single request.
REST specific counting details:
- All counters increase also when the request is invalid, for example wrong payload or missing permissions.
- Bulk measurements creation and bulk alarm status update are counted as a single “requestCount”/“deviceRequestCount” and multiple inbound data transfer count.
SmartREST 1.0 specific counting details:
- Invalid SmartREST requests are not counted, for example when the template doesn’t exist.
- A new template registration is treated as two separate requests. Create a new inventory object which increases “requestCount”, “deviceRequestCount” and “inventoriesCreatedCount”. There is also a second request which binds the template with X-ID, this increases “requestCount” and “deviceRequestCount”.
- Each row in a SmartREST request is transformed into a separate HTTP request. For example, if one SmartREST request contains 10 rows, then 10 separate calls are executed, meaning that both “requestCount” and “deviceRequestCount” are increased by 10.
MQTT specific counting details:
- Invalid requests are counted, for example when sending a message with a wrong template ID.
- Device creation request and automatic device creation are counted.
- Each row/line counts as a separate request.
- Creating custom template counts as a single request, no matter how many rows are send in the request.
- There is one special SmartREST 2.0 template (402 Create location update event with device update) which is doing two things in one call, i.e. create a new location event and update the location of the device. It is counted as two separate requests.
JSON via MQTT specific counting details:
- Invalid requests are counted, for example when the message payload is invalid.
- Bulk creation requests are counted as a single “requestCount”/“deviceRequestCount” and multiple inbound data transfer count.
- Bulk creation requests with a wrong payload are not counted for inbound data transfer count.
Total inbound data transfer
Inbound data transfer refers to the total number of inbound requests performed to transfer data into the Cumulocity IoT platform. This includes sensor readings, alarms, events, commands and alike that are transferred between devices and the Cumulocity IoT platform using the REST and/or MQTT interfaces. Such an inbound request could also originate from a custom microservice, website or any other client.
The table below lists all counters that enhance the Cumulocity IoT tenant statistics and measure the inbound data transfers:
Name | Type | Description |
---|---|---|
measurementsCreatedCount | int | The number of measurements created. Note: The bulk creation of measurements is handled in a way that each measurement is counted individually. |
alarmsCreatedCount | int | The number of alarms created. |
alarmsUpdatedCount | int | The number of updates on alarms. |
eventsCreatedCount | int | The number of events created. |
eventsUpdatedCount | int | The number of updates on events. |
inventoriesCreatedCount | int | The number of managed objects created. |
inventoriesUpdatedCount | int | The number of updates to managed objects. |
totalResourceCreateAndUpdateCount | int | The sum of values above (all inbound transfers). |
See the table below for more information on how the counters above are increased. Additionally, it shows how inbound data transfers are handled for both MQTT and REST:
Type of transfer | MQTT counter information | REST counter information |
---|---|---|
Creation of an alarm in one request | One alarm creation is counted. | One alarm creation is counted via REST. |
Update of an alarm (e.g. status change) | One alarm update is counted. | One alarm update is counted via REST. |
Creation of multiple alarms in one request | Each alarm creation in a single MQTT request will be counted. | Not supported by C8Y (REST does not support creating multiple alarms in one call). |
Update of multiple alarms (e.g. status change) in one request | Each alarm creation in a single MQTT request will be counted. | Not supported by C8Y (REST does not support updating multiple alarms in one call). |
Creation of an event in one request | One event creation is counted. | One event creation is counted. |
Update of an event (e.g. text change) | One event update is counted. | One event update is counted. |
Creation of multiple events in one request | Each event creation in a single MQTT request will be counted. | Not supported by C8Y (REST does not support creating multiple events in one call). |
Update of multiple events (e.g. text change) in one request | Each event update in a single MQTT request will be counted. | Not supported by C8Y (REST does not support updating multiple events in one call). |
Creation of a measurement in one request | One measurement creation is counted. | One measurement creation is counted. |
Creation of multiple measurements in one request | Each measurement creation in a single MQTT request will be counted. Example: If MQTT is used to report 5 measurements, the measurementCreated counter will be incremented by five. | REST allows multiple measurements to be created by sending multiple measurements in one call. In this case, each measurement sent via REST is counted individually. The call itself is not counted. For example, if somebody sends 5 measurements via REST in one call, the corresponding counter will be increased by 5. Measurements with multiple series are counted as a singular measurement. |
Creation of a managed object in one request | One managed object creation is counted. | One managed object creation is counted. |
Update of one managed object (e.g. status change) | One managed object update is counted. | One managed object update is counted. |
Update of multiple managed objects in one request | Each managed object update in a single MQTT request will be counted. | Not supported by C8Y (REST does not support updating multiple managed objects in one call). |
Creation/update of multiple alarms/measurements/events/inventories mixed in a single call. | Each MQTT line is processed separately. If it is a creation/update of an event/alarm/measurement/inventory, the corresponding counter is increased by one. | Not supported by the REST API. |
Assign/unassign of child devices and child assets in one request | One managed object update is counted. | One managed object update is counted. |
MicroserviceUsageStatistics
The microservice usage statistics gathers information on the resource usage for tenants for each subscribed application which are collected on a daily base.
The microservice usage’s information is stored in the resources
object.
Name | Type | Occurs | Description |
---|---|---|---|
cpu | long | 1 | Total number of cpu usage for tenant microservices, specified in CPU milliseconds (1000m = 1 CPU) |
memory | long | 1 | Total number of memory usage for tenant microservices, specified in MB |
usedBy | array | 1..n | Collection of resources usage for each microservice |
usedBy.name | string | 1 | Microservice name |
usedBy.cpu | long | 1 | Number of CPU usage for a single microservice |
usedBy.memory | long | 1 | Number of memory usage for a single microservice |
usedBy.cause | string | 1 | The reason for calculating statistics of the selected microservice |
Response body: TenantUsageStatisticsCollection
Required role: ROLE_TENANT_STATISTICS_READ
Example Request: Get statistics of the current tenant starting on July 1st.
GET /tenant/statistics?dateFrom=2020-07-01
Host: ...
Authorization: Basic ...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantusagestatisticscollection+json; charset=UTF-8; ver=0.9
Content-Length: ...
{
"usageStatistics": [
{
"requestCount": 297180,
"deviceEndpointCount": 2,
"deviceCount": 2,
"resources": {
"cpu": 12006,
"usedBy": [
{
"name": "cep",
"cpu": 6003,
"cause": "Owner",
"memory": 30079
},
{
"name": "device-simulator",
"cpu": 2001,
"cause": "Owner",
"memory": 1073
},
{
"name": "smartrule",
"cpu": 2001,
"cause": "Owner",
"memory": 1074
},
{
"name": "sms-gateway",
"cpu": 2001,
"cause": "Owner",
"memory": 1073
}
],
"memory": 33299
},
"deviceRequestCount": 70540,
"deviceWithChildrenCount": 2,
"eventsCreatedCount": 0,
"subscribedApplications": [
"devicemanagement",
"administration",
"feature-microservice-hosting",
"device-simulator",
"sms-gateway",
"smartrule",
"feature-cep-custom-rules",
"cep",
"cockpit"
],
"alarmsCreatedCount": 0,
"inventoriesUpdatedCount": 5,
"alarmsUpdatedCount": 0,
"eventsUpdatedCount": 0,
"inventoriesCreatedCount": 0,
"storageSize": 91601985,
"measurementsCreatedCount": 0,
"self": "...",
"totalResourceCreateAndUpdateCount": 5,
"day": "2020-07-01T00:00:00.000Z"
}
...
]
}
TenantUsageStatisticsCollection [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsCollection+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
usageStatistics | array | 0..n | List of usage statistics, see above. |
statistics | object | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of tenants. |
next | string | 0..1 | A URI linking to a potential next page of tenants. |
GET a representation of a TenantUsageStatisticsCollection
Query param | type |
---|---|
dateFrom | datetime |
dateTo | datetime |
dateTill (deprecated) | datetime |
Response body: TenantUsageStatisticsCollection
Required role: ROLE_TENANT_STATISTICS_READ
Example Request: Get statistics of current tenant starting Aug 1st, 2014, until today.
GET /tenant/statistics?dateFrom=2014-08-01
Host: ...
Authorization: Basic ...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantusagestatisticscollection+json; charset=UTF-8; ver=0.9
Content-Length: ...
{
"statistics": {
"currentPage": 1,
"pageSize": 5,
"totalPages": 5
},
"self": "<<Collection URL>>",
"usageStatistics": [ {
"day": "2014-08-12T00:00:00.000+02:00",
"deviceCount": 5,
"deviceEndpointCount": 5,
"deviceRequestCount": 101966,
"deviceWithChildrenCount": 5,
"requestCount": 103966,
"self": "...",
"storageSize": 1005442845,
"subscribedApplications": [
"testadmin"
]
},
{
"day": "2014-08-07T00:00:00.000+02:00",
"deviceCount": 30,
"deviceEndpointCount": 15,
"deviceRequestCount": 114378,
"deviceWithChildrenCount": 38,
"requestCount": 116378,
"self": "...",
"storageSize": 1151862557,
"subscribedApplications": [
"testadmin"
]
},
...
]
}
GET a summary of all tenant usage statistics
Query param | type |
---|---|
dateFrom | datetime |
dateTo | datetime |
Response body: application/json
Required role: ROLE_TENANT_MANAGEMENT_READ
Example Request: Get statistics of all tenants starting Aug 1st, 2014, until today.
GET /tenant/statistics/allTenantsSummary?dateFrom=2014-08-01
Host: ...
Authorization: Basic ...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
[
{
"deviceCount": 5,
"deviceEndpointCount": 5,
"deviceRequestCount": 114338,
"deviceWithChildrenCount": 5,
"requestCount": 116378,
"tenantId": "tenant1",
"storageSize": 1151862557,
"subscribedApplications": [
"testadmin"
]
},
{
"deviceCount": 2,
"deviceEndpointCount": 2,
"deviceRequestCount": 114338,
"deviceWithChildrenCount": 2,
"requestCount": 116378,
"tenantId": "tenant2",
"storageSize": 1151862557,
"subscribedApplications": [
"testadmin"
]
},
...
]
TenantUsageStatisticsSummary [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsSummary+json]
GET a representation of a TenantUsageStatisticsSummary
Query param | type |
---|---|
dateFrom | datetime |
dateTo | datetime |
dateTill (deprecated) | datetime |
Response body: TenantUsageStatisticsSummary
Required role: ROLE_TENANT_STATISTICS_READ
Example Request: Get summary of requests and database usage from the start of this month until now.
GET /tenant/statistics/summary
Host: ...
Authorization: Basic ...
Example Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantusagestatisticssummary+json; charset=UTF-8; ver=0.9
Content-Length: ...
{
"self": "...",
"day": "2014-08-21T00:00:00.000+02:00",
"deviceCount": 30,
"deviceEndpointCount": 15,
"deviceRequestCount": 15006838,
"deviceWithChildrenCount": 38,
"requestCount": 15013818,
"storageSize": 983856925,
"subscribedApplications": [
"testadmin"
]
}
Device statistics
Device statistics are collected for each inventory object with at least one measurement, event or alarm. There are no additional checks if the inventory object is marked as device using c8y_IsDevice fragment. Simply when the first measurement, event or alarm is created for a specific inventory object Cumulocity IoT is always considering this as a device and starts counting.
Device statistics are counted with daily and monthy rate.
Only requests with Persistent and Quiescent processing modes are considered when counting device statistics.
The following requests are counted:
- alarm creation and update
- event creation and update
- measurement creation
- bulk measurement creation is counted as multiple requests
- bulk alarm status update is counted as multiple requests
- MQTT and SmartREST requests with multiple rows are counted as multiple requests
Frequently asked questions:
- Are operations on device firmware counted? No, device configuration and firmware update operates on inventory objects, thus they are not counted.
- Are requests done by the UI applications, for example when browsing device details, counted? No, viewing device details performs only GET requests which are not counted.
- Is the clear alarm operation done from the UI counted? Yes, a clear alarm operation in fact performs an alarm update operation and it will be counted as device request.
- Is there any operation performed on the device which is counted? Yes, retrieving device logs requires from the device to create an event and attach a binary with logs to it. Those are two separate requests and both are counted.
- When I have a device with children are the requests counted always to the root device or separately for each child? Separately for each child.
DeviceStatistics
Name | Type | Occurs | Description |
---|---|---|---|
deviceId | long | 1 | Device ID. |
count | long | 1 | Sum of measurement, event and alarms created and updated for a given device. |
DeviceStatisticsCollectionRepresentation [application/json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
statistics | array | 0..n | List of device statistics, see above. |
prev | string | 0..1 | A URI linking to a potential previous page of tenants. |
next | string | 0..1 | A URI linking to a potential next page of tenants. |
GET monthly device statistics
Path param | Type | Description |
---|---|---|
tenantId | String | Tenant ID for which device statistics should be loaded. |
date | String | Date in form of YYYY-MM-dd of queried month (day value is ignored). |
Query param | Type |
---|---|
deviceId | String |
Response body: DeviceStatisticsCollectionRepresentation
Required role: ROLE_TENANT_STATISTICS_READ
Example Request: Get statistics of management tenant for June 2020.
GET /tenant/statistics/device/management/monthly/2020-06-28
Host: ...
Authorization: Basic ...
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
{
"next": "<<Next_Page_URL>>",
"self": "<<Collection URL>>",
"statistics": [
{
"count": 11,
"deviceId": "8708"
},
{
"count": 13,
"deviceId": "13000"
},
{
"count": 15,
"deviceId": "13201"
},
{
"count": 10,
"deviceId": "6902"
}
]
}
GET daily device statistics
Path param | Type | Description |
---|---|---|
tenantId | String | Tenant ID for which device statistics should be loaded. |
date | String | Date in form of YYYY-MM-dd of queried day. |
Query param | Type |
---|---|
deviceId | String |
Response body: DeviceStatisticsCollectionRepresentation
Required role: ROLE_TENANT_STATISTICS_READ
Example Request: Get statistics of management tenant for 28th of June 2020.
GET /tenant/statistics/device/management/daily/2020-06-28
Host: ...
Authorization: Basic ...
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
{
"next": "<<Next_Page_URL>>",
"self": "<<Collection URL>>",
"statistics": [
{
"count": 11,
"deviceId": "8708"
},
{
"count": 13,
"deviceId": "13000"
},
{
"count": 15,
"deviceId": "13201"
},
{
"count": 10,
"deviceId": "6902"
}
]
}
Trusted certificates
TrustedCertificates
Name | Type | Description | Mandatory for PUT/POST |
---|---|---|---|
notAfter | DateTime | Date after which a certificate is no longer valid. | No |
serialNumber | Positive number | Certificate unique serial number. | No |
subject | String | Name of the client to which the certificate belongs. | No |
algorithmName | String | Algorithms used to sign the certificate. | No |
version | String | Version of the encoded certificate. | No |
notBefore | DateTime | Date before which a certificate is not valid. | No |
issuer | String | Entity who has signed and issued the certificate. | No |
fingerprint | String | Unique identifier of the certificate. | No |
name | String | Unique certificate name. | No |
autoRegistrationEnabled | Boolean | Flag for auto registration process. | No |
certInPemFormat | String | Certificate representation in PEM format. | POST: Yes PUT: No |
status | String | Certificate status. | POST: Yes PUT: No |
self | URI | Link to this resource. | No |
GET a certificate from tenant’s trusted certificates
Response body: application/json
Required role: ROLE_TENANT_ADMIN
Example request: Get a certificate from the tenant’s trusted certificates by fingerprint
GET /tenant/tenants/<<tenantId>>/trusted-certificates/<<certificate fingerprint>>
Host: ...
Authorization: Basic ...
Accept: application/json
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"notAfter": "2040-02-13T13:13:00.000Z",
"serialNumber": "<<serial Number>>",
"subject": "CN=IotDevFactory, O=Iot Device Factory, ST=PL, C=EU",
"algorithmName": "SHA256withRSA",
"version": 3,
"notBefore": "2020-02-18T13:13:00.000Z",
"issuer": "<<certificate issuer>>",
"fingerprint": "<<fingerprint>>",
"name": "sample",
"autoRegistrationEnabled": true,
"self": "<<Collection URL>>",
"certInPemFormat": "<<certificate in pem format>>",
"status": "ENABLED"
}
DELETE a certificate from the tenant’s trusted certificates
Response body: application/json
Required role: ROLE_TENANT_ADMIN
Example request: Delete a certificate by fingerprint
DELETE /tenant/tenants/<<tenantId>>/trusted-certificates/<<certificate fingerprint>>
Host: ...
Authorization: Basic ...
Example response:
HTTP/1.1 204 NO CONTENT
PUT - Update an existing certificate
Request body: certificate
Response body: application/json
Required role: ROLE_TENANT_ADMIN
Example request:
PUT /tenant/tenants/<<tenantId>>/trusted-certificates/<<certificate fingerprint>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Accept: application/json
Content-Type: application/json
{
"name" : "newName",
"status" : "DISABLED",
"autoRegistrationEnabled" : true
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"notAfter": "2040-02-13T13:13:00.000Z",
"serialNumber": "<<serial Number>>",
"subject": "CN=IotDevFactory, O=Iot Device Factory, ST=PL, C=EU",
"algorithmName": "SHA256withRSA",
"version": 3,
"notBefore": "2020-02-18T13:13:00.000Z",
"issuer": "<<certificate issuer>>",
"fingerprint": "<<fingerprint>>",
"name": "newName",
"autoRegistrationEnabled": true,
"self": "<<Collection URL>>",
"certInPemFormat": "<<certificate in pem format>>",
"status": "DISABLED"
}
Info: The possible
status
values are ENABLED or DISABLED.
Trusted certificates collection
TrustedCertificates
Name | Type | Occurs | Description |
---|---|---|---|
self | URI | 1 | Link to this resource. |
certificates | TrustedCertificate | 0..n | List of tenant’s trusted certificates, see TrustedCertificates. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | URI | 0..1 | Link to a potential previous page of tenants. |
next | URI | 0..1 | Link to a potential next page of tenants. |
GET a representation of a trusted certificates collection
Response body: application/json
Required role: ROLE_TENANT_ADMIN
Example request: Get a trusted certificates collection for a tenant
GET /tenant/tenants/<<tenantId>>/trusted-certificates
Host: ...
Authorization: Basic ...
Accept: application/json
Example response:
{
"next" : "...",
"prev" : "...",
"self" : "<<Collection URL>>",
"certificates": [
{
"notAfter": "2030-04-22T15:08:33.000Z",
"serialNumber": "<<serial Number>>",
"subject": "CN=IotDevFactory, O=Iot Device Factory, ST=PL, C=EU",
"algorithmName": "SHA256withRSA",
"version": 3,
"notBefore": "2020-04-24T15:08:33.000Z",
"issuer": "<<certificate issuer>>",
"fingerprint": "<<fingerprint>>",
"name": "sample",
"autoRegistrationEnabled": true,
"self": "<<Collection URL>>",
"certInPemFormat": "<<certificate in pem format>>",
"status": "ENABLED"
},
...
],
"statistics": {
"currentPage": 1,
"pageSize": 5
}
POST a certificate to a tenant’s trusted certificates
Example request: Add a certificate to the tenant’s trusted certificates
Required role: ROLE_TENANT_ADMIN
POST /tenant/tenants/<<tenantId>>/trusted-certificates
Host: ...
Authorization: Basic ...
Content-Type: application/json
{
"status" : "ENABLED",
"name" : "sampleName",
"autoRegistrationEnabled" : "true",
"certInPemFormat" : "<<certificate in pem format>>"
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"notAfter": "2040-02-13T13:13:00.000Z",
"serialNumber": "<<serial Number>>",
"subject": "<<certificate subject>>",
"algorithmName": "SHA256withRSA",
"version": 3,
"notBefore": "2020-02-18T13:13:00.000Z",
"issuer": "<<certificate issuer>>",
"fingerprint": "<<fingerprint>>",
"name": "sampleName",
"autoRegistrationEnabled": true,
"self" : "<<Collection URL>>",
"certInPemFormat" : "<<certificate in pem format>>"
"status": "ENABLED"
}
Info: The possible
status
values are ENABLED or DISABLED.