Device credentials

Overview

The device credentials interface consists of the following parts:

Device requests are used to register new devices with a tenant.
Device credentials provide credentials to registered devices.
Device credentials provide endpoint to bulk credentials provision.

For more information on the process of registering devices, see Device integration in the Device SDK guide.

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

New device request collection

NewDeviceRequestCollection [application/vnd.com.nsn.cumulocity.newDeviceRequestCollection+json]

Name	Type	Occurs	Description
self	string	1	A URL linking to this resource.
newDeviceRequests	New device requests	0..n	List of new device requests, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of operations.
next	string	0..1	A URI linking to a potential next page of operations.

POST - Create a new device request

Request body: newDeviceRequest

Response body: newDeviceRequest

Required role: ROLE_DEVICE_CONTROL_ADMIN

Example Request:

POST /devicecontrol/newDeviceRequests
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Authorization: Basic ...
{
  "id" : "1234",
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Content-Length: ...
{
  "id" : "1234",
  "self" : "<<URL of new request>>",
  "status" : "WAITING_FOR_CONNECTION",
}

GET - returns all new device requests

Response body: newDeviceRequestCollection

Required role: ROLE_DEVICE_CONTROL_READ

Example Request:

GET /devicecontrol/newDeviceRequests
Accept: application/vnd.com.nsn.cumulocity.newDeviceRequestCollection+json;ver=...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Location: <<URL of new operation>>
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequestCollection+json;ver=...
Content-Length: ...
{
  "newDeviceRequests": [{
         "id" : "1234",
         "self" : "<<URL of new request>>",
         "status" : "WAITING_FOR_CONNECTION"
  }, {
         "id" : "12345",
         "self" : "<<URL of new request>>",
         "status" : "WAITING_FOR_CONNECTION" }]
}

New device request

NewDeviceRequest [application/vnd.com.nsn.cumulocity.newDeviceRequest+json]

Name	Type	Occurs	Description
id	string	1	Device identifier. Max: 1000 characters. E.g. IMEI
status	string	1	Status of registration, one of: WAITING_FOR_CONNECTION, PENDING_ACCEPTANCE, ACCEPTED
self	string	1	A URL linking to this resource.

GET - returns a new device request

Response body: newDeviceRequest

Required role: ROLE_DEVICE_CONTROL_READ

Example Request:

GET /devicecontrol/newDeviceRequests/<<requestId>>
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Content-Length: ...
{
  "id" : "1234",
  "self" : "<<URL of new request>>",
  "status" : "WAITING_FOR_CONNECTION",
}

DELETE - deletes a new device request

Request body: N/A

Response body: N/A

Required role: ROLE_DEVICE_CONTROL_ADMIN

Example Request:

DELETE /devicecontrol/newDeviceRequests/<<requestId>>
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK

PUT - updates a new device request

Request body: newDeviceRequest

Response body: newDeviceRequest

Required role: ROLE_DEVICE_CONTROL_READ

Example Request:

PUT /devicecontrol/newDeviceRequests/<<requestId>>
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Authorization: Basic ...
{
  "status" : "ACCEPTED",
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
Content-Length: ...
{
  "id" : "1234",
  "self" : "<<URL of new request>>",
  "status" : "ACCEPTED",
}

Device credentials

Device credentials can be enquired by devices that do not have credentials for accessing a tenant yet. Since the device does not have credentials yet, a set of fixed credentials is used for this API. The credentials can be obtained by contacting support. Do not use your tenant credentials with this API.

DeviceCredentials [application/vnd.com.nsn.cumulocity.deviceCredentials+json]

Name	Type	Occurs	Description
id	string	1	Device identifier, e.g. IMEI
tenantId	string	1	Tenant id for authentication
username	string	1	New username
password	string	1	New password
self	string	1	A URL linking to this resource.

POST - creates a device credentials request

Request body: deviceCredentialsn

Response body: deviceCredentials

Required role: ROLE_DEVICE_BOOTSTRAP

Example Request:

POST /devicecontrol/deviceCredentials
Content-Type: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
Authorization: Basic ...
{
  "id" : "12345",
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
Content-Length: ...
{
  "id" : "12345",
  "tenantId" : "test",
  "username" : "device_1234",
  "password" : "3rasfst4swfa",
  "self" : "<<URL to this device credentials>>"
}

Bulk device credentials

Device credentials and basic device representation can be provided from CSV file. CSV file must have 2 sections.

First section is the first line of CSV file. This line contains column names (headers):

Name	Occurs	Description
ID	1	The external id of a device
CREDENTIALS	1	Password for the device’s user
TENANT	0..1	The name of tenant for which registration is executed (allowed only by management tenant)
TYPE	0..1	The type of device representation
NAME	0..1	The name of device representation
ICCID	0..1	The iccid of device (sim card number). If ‘iccid’ appears in file, import adds a fragment ‘c8y_Mobile.iccid’. ‘Iccid’ value is not mandatory for each row, please see below example of http request
IDTYPE	0..1	The type of external Id. If ‘idtype’ doesn’t appear in file, the default value is used. The default value is ‘c8y_Serial’. ‘Idtype’ value is not mandatory for each row, please see below example of http request
PATH	0..1	The path in the groups hierarchy where device is added. Path contains name of each group separated by ‘/', i.e: Main group/Subgroup/…/Last subgroup. If group doesn’t exists, import creates the group
SHELL	0..1	If this column contains value 1, import adds for device ‘Shell’ feature (specifically: c8y_SupportedOperations fragment). ‘Shell’ value is not mandatory for each row, please see below example of http request

Section two is the rest of CSV file. Section two contains devices information. Order and quantity of values must be the same as order and quantity of headers.

Separator is automatically obtained from CSV file. Valid separator values are: ‘\t - tabulation mark’, ‘; - semicolon’ and ‘, - comma’.

Info: Bulk registration creates an elementary representation of the device. Then, the device needs to update it to a full representation with its own status. Device is ready to use only after it’s updated to the full representation. Use following links to read more about Credentials upload and Device integration.

CSV file can appear in many forms (regarding to optional tenant column and occurrence of device information):

When user is logged as management tenant, then columns: ‘id’, ‘credentials’ and ‘tenant’ are mandatory, and credentials for device will be created for tenant mentioned in ‘tenant’ column.
When user is logged in as ‘not management’ tenant i.e. sample_tenant, then columns: ‘id’ and ‘credentials’ are mandatory (if file contains ‘tenant’ column, it is ignored and credentials for device will be created for tenant that is logged in).
When user wants to add information about device, columns ‘type’ nad ‘name’ must appear in CSV file.
When user wants to add information about sim card number, columns ‘type’, ‘name’ and ‘iccid’ must appear in CSV file.
When user wants to change the type of external id, columns ‘type’, ‘name’ and ‘idtype’ must appear in CSV file.
When user wants to add device to group, columns ‘type’, ‘name’ and ‘path’ must appear in CSV file.
When user wants to add shell feature, columns ‘type’, ‘name’ and ‘shell’ must appear in CSV file and column ‘shell’ must contain value 1.

It is possible to define custom external ID mappings and some custom device properties which are added to newly created devices during registration:

To add a custom external ID mapping, enter the external ID type as the header of the last column with the prefix “external-”, e.g. to add an external ID mapping of type ‘c8y_Imei’, enter ‘external-c8y_Imei’ in the last column header. The value of this external ID type should be set in the corresponding column of the data rows.
To add a custom property to a registered device, enter the custom property name as a header, e.g. “myCustomProperty”, and the value would be in the rows below.

The custom device properties mapping has following limitations:

Braces ‘{}’ used in data rows will be interpreted as strings of “{}”. The system will interpret the value as an object when some custom property is added, e.g. put ‘com_cumulocity_model_Agent.active’ into headers row and ‘true’ into data row to create an object ‘“com_cumulocity_model_Agent”: {“active”: “true”}"’.
It is not possible to add array values via bulk registration.

BulkNewDeviceRequest [application/vnd.com.nsn.cumulocity.bulkNewDeviceRequest+json]

<<<<<<< HEAD ======= >>>>>>> 5de3b2eb... fixed occurences of 'id', fixed first half of tables <<<<<<< HEAD ======= >>>>>>> 5de3b2eb... fixed occurences of 'id', fixed first half of tables <<<<<<< HEAD ======= >>>>>>> 5de3b2eb... fixed occurences of 'id', fixed first half of tables <<<<<<< HEAD ======= >>>>>>> 5de3b2eb... fixed occurences of 'id', fixed first half of tables <<<<<<< HEAD ======= >>>>>>> 5de3b2eb... fixed occurences of 'id', fixed first half of tables

Name	Type	Occurs	Description
numberOfAll	int	1	Number of lines processed from CSV file, without first line (column headers)	Number of lines processed from the CSV file, without the first line (column headers).
numberOfCreated	int	1	Number of created device credentials.
numberOfFailed	int	1	Number of failed creation of device credentials	Number of failed creations of device credentials.
numberOfSuccessful	int	1	Number of successful creation of device credentials, contains create and update operations	Number of successful creations of device credentials, contains create and update operations.
credentialUpdatedList	array	0..n	Array with updated device credentials.
credentialUpdatedList.bulkNewDeviceStatus	string	1	Device credentials creation status. Possible values: CREATED, FAILED, CREDENTIAL_UPDATED
credentialUpdatedList.deviceId	string	1	Id of device	ID of the device.
failedCreationList	array	0..n	Array with updated device credentials.
failedCreationList.bulkNewDeviceStatus	string	1	Device credentials creation status. Possible values: CREATED, FAILED, CREDENTIAL_UPDATED
failedCreationList.deviceId	string	0..1	Id of device, appears if application can obtain it from file	ID of the device, appears if the application can obtain it from the file.
failedCreationList.failureReason	string	1	Reason of error.
failedCreationList.line	string	1	Line with error.

POST - creates a bulk device credentials request

Request body: multipart/form-data

Response body: bulkNewDeviceRequest

Required role: ROLE_DEVICE_CONTROL_ADMIN

Example Request:

POST /devicecontrol/bulkNewDeviceRequests
Content-Type: multipart/form-data; boundary=myBoundary
Accept: application/json
Authorization: Basic ...

--myBoundary
Content-Disposition: form-data; name="file"
Content-Type: plain/text

ID;CREDENTIALS;TYPE;NAME;ICCID;IDTYPE;PATH;SHELL
id_101;abcd1234;type_of_device;Device 101;111111111;;csv device/subgroup0;1
id_102;abcd1234;type_of_device;Device 102;222222222;;csv device/subgroup0;0
id_111;abcd1234;type_of_device;Device 111;333333333;c8y_Imei;csv device1/subgroup1;0
id_112;abcd1234;type_of_device;Device 112;444444444;;csv device1/subgroup1;1
id_121;abcd1234;type_of_device;Device 121;555555555;;csv device1/subgroup2;1
id_122;abcd1234;type_of_device;Device 122;;;csv device1/subgroup2;
id_131;abcd1234;type_of_device;Device 131;;;csv device1/subgroup3;
--myBoundary

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/vnd.com.nsn.cumulocity.bulkNewDeviceRequest+json;ver=...
Content-Length: ...
{
    "credentialUpdatedList" : [
        {
            "bulkNewDeviceStatus" : "CREDENTIAL_UPDATED",
            "deviceId" : "id04"
        }
    ],
    "failedCreationList" : [
        {
            "bulkNewDeviceStatus" : "FAILED",
            "deviceId" : "id04",
            "failureReason" : "failure",
            "line" : "DeviceInfo{id='id5', credentials='credentials3', tenant='tenant3'}"
        }
    ],
    "numberOfAll" : 5,
    "numberOfCreated" : 3,
    "numberOfFailed" : 1,
    "numberOfSuccessful" : 4
}