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 product 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

The device credentials and the basic device representation can be provided from a CSV file which must be UTF-8 or ANSI encoded. The CSV file must have 2 sections.

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

TENANT

Name	Occurs	Description
ID	1	External ID of the device.
CREDENTIALS	0..1	Password for the device’s user. If the device uses certificates, this is not required.
AUTH_TYPE	0..1	Required authentication type for the device's user. If the device uses credentials, this can be skipped or filled with BASIC. Devices that use certificates must set CERTIFICATES.
0..1	The name of the tenant for which registration is executed (allowed only by the management tenant).
TYPE	0..1	The type of the device representation.
NAME	0..1	The name of the device representation.
ICCID	0..1	The ICCID of the device (SIM card number). If "iccid" appears in the file, the import adds a fragment "c8y_Mobile.iccid". The "iccid" value is not mandatory for each row. See the example of an HTTP request below.
IDTYPE	0..1	The type of external ID. If "idtype" doesn’t appear in the file, the default value is used. The default value is "c8y_Serial". The "idtype" value is not mandatory for each row. See the example of an HTTP request below.
PATH	0..1	The path in the groups hierarchy where the device is added. The path contains the name of each group separated by '/', e.g. "main group/subgroup/…/last subgroup". If the group doesn’t exist, the import creates the group.
SHELL	0..1	If this column contains the value "1", the import adds the Shell feature for the device (specifically: "c8y_SupportedOperations" fragment). The "shell" value is not mandatory for each row. See the example of an HTTP request below.

Section two is the remaining part of the CSV file and it contains the device information. The order and quantity of values must be the same as the order and quantity of headers.

The separator is automatically obtained from the CSV file. Valid separator values are tabulation mark “\t”, 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. The device is ready to use only after it is updated to the full representation. For more information on credentials upload refer to Device Management > Connecting devices > To bulk-register devices in the User guide. For more information on device integration refer to Device integration using REST > Device integration in the Device SDK guide.

The CSV file can have in many forms, depending on the optional tenant column and device information:

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

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 the 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 the headers row and “true” into the 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]

Name	Type	Occurs	Description
numberOfAll	int	1	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 creations of device credentials.
numberOfSuccessful	int	1	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 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 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
}