Sign in
latestOpenAPI 3.1.0Apache License Version 2.02026-08-17498525913.3 KB

40169ccdec5c

device-controller

Create Device (saveDevice) with credentials

Create or update the Device. When creating device, platform generates Device Id as time-based UUID. Requires to provide the Device Credentials object as well as an existing device profile ID or use "default". You may find the example of device with different type of credentials below:

  • Credentials type: <b>"Access token"</b> with <b>device profile ID</b> below:
{
  "device": {
    "name":"Name_DeviceWithCredantial_AccessToken",
    "label":"Label_DeviceWithCredantial_AccessToken",
    "deviceProfileId":{
      "id":"9d9588c0-06c9-11ee-b618-19be30fdeb60",
      "entityType":"DEVICE_PROFILE"
     }
   },
  "credentials": {
    "credentialsType": "ACCESS_TOKEN",
    "credentialsId": "6hmxew8pmmzng4e3une2"
   }
}
  • Credentials type: <b>"Access token"</b> with <b>device profile default</b> below:
{
  "device": {
    "name":"Name_DeviceWithCredantial_AccessToken_Default",
    "label":"Label_DeviceWithCredantial_AccessToken_Default",
    "type": "default"
   },
  "credentials": {
    "credentialsType": "ACCESS_TOKEN",
    "credentialsId": "6hmxew8pmmzng4e3une3"
   }
}
  • Credentials type: <b>"X509"</b> with <b>device profile ID</b> below:

Note: <b>credentialsId</b> - format <b>Sha3Hash</b>, <b>certificateValue</b> - format <b>PEM</b> (with "--BEGIN CERTIFICATE----" and -"----END CERTIFICATE-").

{
  "device": {
    "name":"Name_DeviceWithCredantial_X509_Certificate",
    "label":"Label_DeviceWithCredantial_X509_Certificate",
    "deviceProfileId":{
      "id":"9d9588c0-06c9-11ee-b618-19be30fdeb60",
      "entityType":"DEVICE_PROFILE"
     }
   },
  "credentials": {
    "credentialsType": "X509_CERTIFICATE",
    "credentialsId": "84f5911765abba1f96bf4165604e9e90338fc6214081a8e623b6ff9669aedb27",
    "credentialsValue": "-----BEGIN CERTIFICATE----- MIICMTCCAdegAwIBAgIUI9dBuwN6pTtK6uZ03rkiCwV4wEYwCgYIKoZIzj0EAwIwbjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMRowGAYDVQQKDBFUaGluZ3NCb2FyZCwgSW5jLjEwMC4GA1UEAwwnZGV2aWNlQ2VydGlmaWNhdGVAWDUwOVByb3Zpc2lvblN0cmF0ZWd5MB4XDTIzMDMyOTE0NTYxN1oXDTI0MDMyODE0NTYxN1owbjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMRowGAYDVQQKDBFUaGluZ3NCb2FyZCwgSW5jLjEwMC4GA1UEAwwnZGV2aWNlQ2VydGlmaWNhdGVAWDUwOVByb3Zpc2lvblN0cmF0ZWd5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9Zo791qKQiGNBm11r4ZGxh+w+ossZL3xc46ufq5QckQHP7zkD2XDAcmP5GvdkM1sBFN9AWaCkQfNnWmfERsOOKNTMFEwHQYDVR0OBBYEFFFc5uyCyglQoZiKhzXzMcQ3BKORMB8GA1UdIwQYMBaAFFFc5uyCyglQoZiKhzXzMcQ3BKORMA8GA1UdEwEB/wQFMAMBAf8wCgYIKoZIzj0EAwIDSAAwRQIhANbA9CuhoOifZMMmqkpuld+65CR+ItKdXeRAhLMZuccuAiB0FSQB34zMutXrZj1g8Gl5OkE7YryFHbei1z0SveHR8g== -----END CERTIFICATE-----"
   }
}
  • Credentials type: <b>"MQTT_BASIC"</b> with <b>device profile ID</b> below:
{
  "device": {
    "name":"Name_DeviceWithCredantial_MQTT_Basic",
    "label":"Label_DeviceWithCredantial_MQTT_Basic",
    "deviceProfileId":{
      "id":"9d9588c0-06c9-11ee-b618-19be30fdeb60",
      "entityType":"DEVICE_PROFILE"
     }
   },
  "credentials": {
    "credentialsType": "MQTT_BASIC",
    "credentialsValue": "{\"clientId\":\"5euh5nzm34bjjh1efmlt\",\"userName\":\"onasd1lgwasmjl7v2v7h\",\"password\":\"b9xtm4ny8kt9zewaga5o\"}"
   }
}
  • You may find the example of <b>LwM2M</b> device and <b>RPK</b> credentials below:

Note: LwM2M device - only existing device profile ID (Transport configuration -> Transport type: "LWM2M".

{
  "device": {
    "name":"Name_LwRpk00000000",
    "label":"Label_LwRpk00000000",
    "deviceProfileId":{
      "id":"a660bd50-10ef-11ee-8737-b5634e73c779",
      "entityType":"DEVICE_PROFILE"
     }
   },
  "credentials": {
    "credentialsType": "LWM2M_CREDENTIALS",
    "credentialsId": "LwRpk00000000",
    "credentialsValue":
       "{\"client\":{ \"endpoint\":\"LwRpk00000000\", \"securityConfigClientMode\":\"RPK\", \"key\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\"   }, \"bootstrap\":{ \"bootstrapServer\":{ \"securityMode\":\"RPK\", \"clientPublicKeyOrId\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\", \"clientSecretKey\":\"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgd9GAx7yZW37autew5KZykn4IgRpge/tZSjnudnZJnMahRANCAARQQHE2X9Fxgk2byaT3ULJVeggmJE5gOVdxJKorp7lsMfA5bhmI3aU2ddqXIXQnHDwxsDK2cMwRFfICNrlUQx5V\"}, \"lwm2mServer\":{ \"securityMode\":\"RPK\", \"clientPublicKeyOrId\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\", \"clientSecretKey\":\"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgd9GAx7yZW37autew5KZykn4IgRpge/tZSjnudnZJnMahRANCAARQQHE2X9Fxgk2byaT3ULJVeggmJE5gOVdxJKorp7lsMfA5bhmI3aU2ddqXIXQnHDwxsDK2cMwRFfICNrlUQx5V\"}} }"
   }
}

Remove 'id', 'tenantId' and optionally 'customerId' from the request body example (below) to create new Device entity.

Available for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority.

post/api/device-with-credentials

Query parameters

nameConflictPolicy'FAIL' | 'UNIQUIFY'

Optional value of name conflict policy. Possible values: FAIL or UNIQUIFY. If omitted, FAIL policy is applied. FAIL policy implies exception will be thrown if an entity with the same name already exists. UNIQUIFY policy appends a suffix to the entity name, if a name conflict occurs.

uniquifySeparatorstring

Optional value of name suffix separator used by UNIQUIFY policy. By default, underscore separator is used. For example, strategy is UNIQUIFY, separator is '-'; if a name conflict occurs for entity name 'test-name', created entity will have name like 'test-name-7fsh4f'.

uniquifyStrategy'RANDOM' | 'INCREMENTAL'

Optional value of uniquify strategy used by UNIQUIFY policy. Possible values: RANDOM or INCREMENTAL. By default, RANDOM strategy is used, which means random alphanumeric string will be added as a suffix to entity name. INCREMENTAL implies the first possible number starting from 1 will be added as a name suffix. For example, strategy is UNIQUIFY, uniquify strategy is INCREMENTAL; if a name conflict occurs for entity name 'test-name', created entity will have name like 'test-name-1.

Request body

Example request

{
  "device": {
    "id": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "DEVICE"
    },
    "createdTime": 1609459200000,
    "tenantId": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "TENANT"
    },
    "customerId": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "CUSTOMER"
    },
    "name": "A4B72CCDFF33",
    "type": "Temperature Sensor",
    "label": "Room 234 Sensor",
    "deviceProfileId": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "DEVICE_PROFILE"
    },
    "firmwareId": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "OTA_PACKAGE"
    },
    "softwareId": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "OTA_PACKAGE"
    },
    "additionalInfo": {}
  },
  "credentials": {
    "id": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9"
    },
    "createdTime": 1609459200000,
    "deviceId": {
      "id": "784f394c-42b6-435a-983c-b7beff2784f9",
      "entityType": "DEVICE"
    },
    "credentialsId": "Access token or other value that depends on the credentials type",
    "credentialsValue": "Null in case of ACCESS_TOKEN. See model definition."
  }
}

Response

OK

createdTimeinteger

Timestamp of the device creation, in milliseconds

namestring required

Unique Device Name in scope of Tenant

typestring

Device Profile Name

labelstring

Label that may be used in widgets

versioninteger
{"stackTrail":"components:schemas:JsonNode","oasType":"schema","type":"unknown","description":"A value representing the any type (object or primitive)","example":{}}

Example response

{
  "id": {
    "id": "784f394c-42b6-435a-983c-b7beff2784f9",
    "entityType": "DEVICE"
  },
  "createdTime": 1609459200000,
  "tenantId": {
    "id": "784f394c-42b6-435a-983c-b7beff2784f9",
    "entityType": "TENANT"
  },
  "customerId": {
    "id": "784f394c-42b6-435a-983c-b7beff2784f9",
    "entityType": "CUSTOMER"
  },
  "name": "A4B72CCDFF33",
  "type": "Temperature Sensor",
  "label": "Room 234 Sensor",
  "deviceProfileId": {
    "id": "784f394c-42b6-435a-983c-b7beff2784f9",
    "entityType": "DEVICE_PROFILE"
  },
  "firmwareId": {
    "id": "784f394c-42b6-435a-983c-b7beff2784f9",
    "entityType": "OTA_PACKAGE"
  },
  "softwareId": {
    "id": "784f394c-42b6-435a-983c-b7beff2784f9",
    "entityType": "OTA_PACKAGE"
  },
  "additionalInfo": {}
}