Security Services REST APIs (1.1.29)

Download OpenAPI specification:Download

Customer REST APIs used to connect to Security Services Platform.

Authentication

authId

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Authentication APIs

/authenticate

Authenticates an APIKey and matching secret and returns an AuthToken and RefreshToken

Request Body schema: application/json
APIKey
required
string

The APIKey created and provided to the client by u-blox support. This is one of the two values (including the APISecret) required to create the Authorization (AuthToken) and Refresh (RefreshToken) headers. It must be current and valid for the client.

APISecret
required
string

The APISecret linked to and created at the same time as the APIKey. The APISecret will also be provided to the client by u-blox support - it must be current and valid for the APIKey.

Responses

Request samples

Content type
application/json
{
  • "APIKey": "0d636af8-d001-49ba-86d3-80f21272c14a",
  • "APISecret": "nqnazbOMuKAalu9KZwHKyN7tnJua96ki"
}

Response samples

Content type
application/json
{
  • "AuthToken": "eyJraWQiOiJwZFc0elY4dGlEaDhjUWREUTIrOXQ5SmhMZ2w1bGpNTW5Lcm1aVTRxV1M0PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJmNTEwZTAxZS1lOWNlLTRiNGYtOTI2Mi1lOWE3NGJiNjhhNGUiLCJhdWQiOiI1ZTZydmMwb2Fhc2FwYWs1NHZjNTFxdmRkMSIsImV2ZW50X2lkIjoiYzViOGEzMWEtYjc1My00NjEwLTg3MWUtNWRkOGFiZmZlMjk1IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NzY0ODg4MTgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1pvNmExYzI5SSIsImNvZ25pdG86dXNlcm5hbWUiOiI3NTExMmQ0OC1iMjFkLTRmYzItYmJlMS01MjBmMWYxY2IxYWY0djdqS3MzcFlPNlp4S1o3NTh0MUhMNnEzQ3FQZkV2OWx5THRCZzUzIiwiZXhwIjoxNTc2NDkyNDE4LCJpYXQiOjE1NzY0ODg4MTh9.KEqQlBGji-x6q48N0QC92MDyYaqvoE1yjlDZIT-Wm83JTd_N4gg04Fft1LhBf_n5kcaG8ozNOcoQqnvGSgRc3WdiRRt10VLjWelLxTCZv-KfdE_yytxMQyz8okW934hyDCHEICCPFcVFuguNKgLvROaRbrdyXvjxRp19wJMoFIxTyq_HVKNsXE4pMjRzOe8aUVPknv-ahwWptOGmkLItn6kPvKze5dRjrZ_TCX1JA9ctWutQsA3xVudkAigX5abPU67ERCcC18MWcb2suJdKAJ_LEbNu9oaVxhK4BKyAsGXgzfJDcmzmvah-HpfRZILKOk2aFI3pJuT5bIvRk714DA",
  • "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.BET2RibujxYPTb8J9MmsvK567rSyNKinEWKUMW5DwXDmN-_iK78UVDeNZcsBMHat7Q0QDPRV_JJwtW9WUb9QIT1PboCi8G7Umq-UzMY0VKgEgjzvC2dz0USDljE7rI9PsizL35g52WOYdyjuOz-5ywmtzJW_Gm4w6pJ7tZFV3C_fzD107QVWIMZJkEcdz_qXMh_xrtHtIjPtgtVwydfTugiBKUIdKp1MDXayEXHObCRnQ-wT_PYPf5kpyK2HdrkkafZ-bLcT1Ot1xX5Won3oReYvaaRGjODbzpSCmTRK19-vtUHdmbijOtlwbXIib2ywy5I0NFI_oz1vB6m14LUuwQ.5jr8P9WBumUqQ0py.n-DjibjN8GgrMlzushDQNCCM1ycqD-QXCBoGCbfdKTGasREloXu8-GOgdABlkHdkUIWbls8Yy081p2ralIZJ5ARrhpaLspuxYf3uCUO2sHGJoSXpyNUuI74je2qGu6SVMwmJsa3Mw_aduAjIldcfYk_BqCVrjAO4Hr33pkJJsVVkr9vgvSRA-Xd59QB_XcNU0Z871JeMT2tLkJlZKUJ7xQhAK5Uu1zozoUJpSsj5wmGo1wrMGNUKQ0Hbg0Y8j9yFJNeGbu8LRZeCUAT3T9KbvegihzpjBdlAg7qNBE8DaiwluYEhNIM9SCR5U8S9qO9X6CxJy4D408CWkid4iiU3rmJ7JO5fJiQQJ1YJob0W9KOimYZ8k9llFfYY8SpFq3N7q0qR_vIS0PgwE-rofuHafWUrksE-GXfa_L9HNAzrYdNA4sXwEUCQsv0cvcm-UklL02HMSLXv_A0y4O-UuSORe9ktpGog2pNm8Z-w6haDtszTu-7PMG18Rx-3B2luoX6rX7NadbFiEOpYl7jq5e1yW2gqntt_p66TWLmaB2_Hi47J2dkTszAhHc6L-kWqQ-MmOB2RuHHyvj0-NH-kiRIDH8NwfJYS36Z1YS1bwtxixkLeZ4szpl0QDB18MZEVJCr-98r0-4jXcIb05uL-piJtJr3hozjxGphMrV1ZcQe28NppkHUCPP99g8M7Rr_2e4v-TZWEN2twcKenciF6j6Vzgb-jD9xTNygIj7xQuw6GIw1RUIt9WpoKwL8sXZwpzQ-LXWvP6uw4lYfovGeUcx6HsUX3HKoSpMQnbmrIUmWmM4TyKLnrvSnVzwtQfzu6IIEC_bvG_O9Ke7a87rq8n9i9XkrpjmkXTcmw5Pp-wRHVlNriYvE_G_PhB5f2aBs9G-zuA5ybKIOExE-KRCCouji53lBJrgtO_Q0tfyhqjXW4zYSF-vStFgLAuEbYDjTiY0RB23OpPn2AVBVuQtFvxjKoBqgzTiPXhrsu_1QQ6joLEw5pJXJ07vMI1yWMj8Qro6MUwfdwappSjsEoopE9XG38w41yTpOj29spfjNWhVMG6e7Ohy5OvQ7_LK6_RgbbOHSajTXAv_dGhq2NN6uotnkTDYmoWxVVK5RoKBFlwBnyyB6H5s6rRcPLJIyXlySTOlL66rOIZbHz92eYmCC334dMiDEMuZcAjwgDsMOX8nfFIBFVNgdmlQYk1fxrU_JG5uvm1_dhmI3bKrmOMB9OdwGHoEyNd8fYcFVacB9hhhY_ejLe_2rkNhPbu5ONGeq6MrFGaa-we_BBjA25X9Zlr8Y8DDnjYQsOYRs3acA7uuy-gJ6AdQ7CYuZtLamN4JlXMhQP6VzQYVULYDooMSwOI4kqhotGLW0YM4XmC9x8nc3A-dRZW5fNA6A3WeqEJuwZ8Vpiwh8.1rMwObTlw4-WhgQA6W0Ixg"
}

/refreshauthtoken

Allows the creation of a new AuthToken. The RefreshToken can be used for 3 days

Authorizations:
Request Body schema: application/json
APIKey
required
string

The APIKey created and provided to the client by u-blox support. It must be current and valid for the client.

RefreshToken
required
string

The Token used to create a new Authorization header. The RefreshToken can only be used to create a new AuthToken if the RefreshToken is not more than 3 days old.

Responses

Request samples

Content type
application/json
{
  • "APIKey": "0d636af8-d001-49ba-86d3-80f21272c14a",
  • "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.BET2RibujxYPTb8J9MmsvK567rSyNKinEWKUMW5DwXDmN-_iK78UVDeNZcsBMHat7Q0QDPRV_JJwtW9WUb9QIT1PboCi8G7Umq-UzMY0VKgEgjzvC2dz0USDljE7rI9PsizL35g52WOYdyjuOz-5ywmtzJW_Gm4w6pJ7tZFV3C_fzD107QVWIMZJkEcdz_qXMh_xrtHtIjPtgtVwydfTugiBKUIdKp1MDXayEXHObCRnQ-wT_PYPf5kpyK2HdrkkafZ-bLcT1Ot1xX5Won3oReYvaaRGjODbzpSCmTRK19-vtUHdmbijOtlwbXIib2ywy5I0NFI_oz1vB6m14LUuwQ.5jr8P9WBumUqQ0py.n-DjibjN8GgrMlzushDQNCCM1ycqD-QXCBoGCbfdKTGasREloXu8-GOgdABlkHdkUIWbls8Yy081p2ralIZJ5ARrhpaLspuxYf3uCUO2sHGJoSXpyNUuI74je2qGu6SVMwmJsa3Mw_aduAjIldcfYk_BqCVrjAO4Hr33pkJJsVVkr9vgvSRA-Xd59QB_XcNU0Z871JeMT2tLkJlZKUJ7xQhAK5Uu1zozoUJpSsj5wmGo1wrMGNUKQ0Hbg0Y8j9yFJNeGbu8LRZeCUAT3T9KbvegihzpjBdlAg7qNBE8DaiwluYEhNIM9SCR5U8S9qO9X6CxJy4D408CWkid4iiU3rmJ7JO5fJiQQJ1YJob0W9KOimYZ8k9llFfYY8SpFq3N7q0qR_vIS0PgwE-rofuHafWUrksE-GXfa_L9HNAzrYdNA4sXwEUCQsv0cvcm-UklL02HMSLXv_A0y4O-UuSORe9ktpGog2pNm8Z-w6haDtszTu-7PMG18Rx-3B2luoX6rX7NadbFiEOpYl7jq5e1yW2gqntt_p66TWLmaB2_Hi47J2dkTszAhHc6L-kWqQ-MmOB2RuHHyvj0-NH-kiRIDH8NwfJYS36Z1YS1bwtxixkLeZ4szpl0QDB18MZEVJCr-98r0-4jXcIb05uL-piJtJr3hozjxGphMrV1ZcQe28NppkHUCPP99g8M7Rr_2e4v-TZWEN2twcKenciF6j6Vzgb-jD9xTNygIj7xQuw6GIw1RUIt9WpoKwL8sXZwpzQ-LXWvP6uw4lYfovGeUcx6HsUX3HKoSpMQnbmrIUmWmM4TyKLnrvSnVzwtQfzu6IIEC_bvG_O9Ke7a87rq8n9i9XkrpjmkXTcmw5Pp-wRHVlNriYvE_G_PhB5f2aBs9G-zuA5ybKIOExE-KRCCouji53lBJrgtO_Q0tfyhqjXW4zYSF-vStFgLAuEbYDjTiY0RB23OpPn2AVBVuQtFvxjKoBqgzTiPXhrsu_1QQ6joLEw5pJXJ07vMI1yWMj8Qro6MUwfdwappSjsEoopE9XG38w41yTpOj29spfjNWhVMG6e7Ohy5OvQ7_LK6_RgbbOHSajTXAv_dGhq2NN6uotnkTDYmoWxVVK5RoKBFlwBnyyB6H5s6rRcPLJIyXlySTOlL66rOIZbHz92eYmCC334dMiDEMuZcAjwgDsMOX8nfFIBFVNgdmlQYk1fxrU_JG5uvm1_dhmI3bKrmOMB9OdwGHoEyNd8fYcFVacB9hhhY_ejLe_2rkNhPbu5ONGeq6MrFGaa-we_BBjA25X9Zlr8Y8DDnjYQsOYRs3acA7uuy-gJ6AdQ7CYuZtLamN4JlXMhQP6VzQYVULYDooMSwOI4kqhotGLW0YM4XmC9x8nc3A-dRZW5fNA6A3WeqEJuwZ8Vpiwh8.1rMwObTlw4-WhgQA6W0Ixg"
}

Response samples

Content type
application/json
{
  • "AuthToken": "eyJraWQiOiJwZFc0elY4dGlEaDhjUWREUTIrOXQ5SmhMZ2w1bGpNTW5Lcm1aVTRxV1M0PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJmNTEwZTAxZS1lOWNlLTRiNGYtOTI2Mi1lOWE3NGJiNjhhNGUiLCJhdWQiOiI1ZTZydmMwb2Fhc2FwYWs1NHZjNTFxdmRkMSIsImV2ZW50X2lkIjoiYzViOGEzMWEtYjc1My00NjEwLTg3MWUtNWRkOGFiZmZlMjk1IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NzY0ODg4MTgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1pvNmExYzI5SSIsImNvZ25pdG86dXNlcm5hbWUiOiI3NTExMmQ0OC1iMjFkLTRmYzItYmJlMS01MjBmMWYxY2IxYWY0djdqS3MzcFlPNlp4S1o3NTh0MUhMNnEzQ3FQZkV2OWx5THRCZzUzIiwiZXhwIjoxNTc2NDkyNjUzLCJpYXQiOjE1NzY0ODkwNTN9.JL69Bk9B1VYI8ZIKbZBYFJM7LWVEheyHSOc_LA3o3ZNQieYjOOJmTc56qOsNNPX03j2G91OXnaZqJDAhkuz759WHFgTZ4PQt45VhnFSJRf-cxXEGKIYY9vS5Pyi9USpOuKt6zRuD1yoZTsRScQaKV5jV0kDmu1f4nwmM38XFKY7NL37-AntoYk4pRLeuK3zQt3AHHFNeBXBEckD1HakdEXWubRXj7x9dWZ1Q00ttw6Ca9FN_UHcRg265QOhhGzEYd7q-f8VTDDgHQrvNL43UJ9-Xl_WLG-26q9IxNwVRW0N_veIu4w9TLYLHczWfBLEH86ZqA3K7E2KiANoxVXj0vA"
}

Device Profile APIs

/deviceprofile/get

The API call to get a list of all created Device Profiles. This API returns a paginated response, which means in order to get to next set of records, you would have to give PageNumber in request body.

Authorizations:
Request Body schema: application/json
TagNames
Array of strings

[mutually exclusive]
Give a list of tag names, and all device profiles associated with them will be returned.
If you provide ProfileName as input parameter, and this as well, you will receive an error.

ProfileName
string

[mutually exclusive]
If you want to retrieve data of a single profile, use this field.

Note: ProfileName is case-sensitive.

If you provide TagNames as input parameter, and this as well, you will receive an error.

PageNumber
number

Defaults to 1 if not given.

Responses

Request samples

Content type
application/json
Example
{
  • "TagNames": [
    ],
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "DeviceProfiles": [
    ],
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 15
}

/deviceprofile/bootstrapprovisioning/set

Set or update feature authorizations (Local Data Protection, Local Chip-to-Chip Security, Local Chip-to-Chip Security Key Pairing, ZTPV1), and network parameters (Security Heartbeat) on new devices (i.e.: they have not bootstrapped). Provisioning will happen when the device bootstraps.

Enables or disables feature authorization and network parameters on the list of devices that belong to provided DeviceProfileUID in the request.

Authorizations:
Request Body schema: application/json
DeviceProfileUID
required
string^(.*)$

DeviceProfileUID against which security features will be set.

required
object

The desired feature authorizations and/or network parameters to be provisioned on DeviceProfileUID.
Note: Only Local Data Protection (LocalDPR), Local Chip-to-Chip Security (LocalC2C), Local Chip-to-Chip Key Pairing (LocalC2CKeyPairing), and Zerotouch provisioning (ZTPV1) security services can be updated using this API. In addition, Security Heartbeat (SecurityHeartbeatInSec) network parameter can also be set using this API.

Responses

Request samples

Content type
application/json
Example
{
  • "DeviceProfileUID": "AyvylmHVdUiHQzUaCjOmC",
  • "Provisioning": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Bad Request"
}

/deviceprofile/bootstrapprovisioning/get

Gets feature authorization and network parameters that were set on new devices (i.e.: they have not bootstrapped).

Authorizations:
Request Body schema: application/json
DeviceProfileUID
required
string^(.*)$

DeviceProfileUID against which security features were set.

Responses

Request samples

Content type
application/json
{
  • "DeviceProfileUID": "AyvylmHVdUiHQzUaCjOmC"
}

Response samples

Content type
application/json
{
  • "DeviceProfileUID": "AyvylmHVdUiHQzUaCjOmC",
  • "DesiredProperties": {
    }
}

/deviceprofile/bootstrapprovisioning/delete

Deletes feature authorizations and network parameters that were set to be applied on new devices (i.e.: they have not bootstrapped), as if they were never set.

All devices that have already bootstrapped will not be affected by this change.

Authorizations:
Request Body schema: application/json
DeviceProfileUID
required
string^(.*)$

DeviceProfileUID against which security features will be deleted.

Responses

Request samples

Content type
application/json
{
  • "DeviceProfileUID": "AyvylmHVdUiHQzUaCjOmC"
}

Response samples

Content type
application/json
{
  • "message": "Bad Request"
}

Device APIs

/device/list/get

The API call to get list of all devices in your account. You can also provide a filter to either get whitelisted or blacklisted devices.

Authorizations:
Request Body schema: application/json
Filter
string
Enum: "ALL" "WHITELISTED" "BLACKLISTED"

The Filter to apply on devices.

PageNumber
integer

Responses

Request samples

Content type
application/json
Example
{
  • "Filter": "BLACKLISTED",
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "ROTPublicUIDs": [
    ],
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 300
}

/device/whitelist/add

The API call to add or update list of devices that are whitelisted. This list is important because when a device bootstraps (in ACTIVATED state), feature authorizations will be applied only if the device is in this whitelist, otherwise, the device will bootstrap in ALLOCATED state with no feature authorizations enabled (as set at device profile level).

You can add a device to whitelist using ROTPublicUIDs and/or IMEIs

Instead of providing device info in request body, you can also upload the information in CSV file. If you wish to upload data using CSV, please keep in mind two things:

  1. Content-Type must be set to application/octet-stream
  2. Format of the file must be:
    1. First row should be header row, with names and data in following order:
      1. Id
      2. Type
      3. Action
    2. Second row onwards should be data rows. Sample data row should look like this:
      • 00020001003ffff,ROTPublicUID,ADD

    WHERE
    1. Id is ROTPublicUID that you want to whitelist.
    2. TYPE is the type of ID provided above. Possible value is:
      1. ROTPublicUID
    3. Action is what to do with the row: should it be added to or deletd from the whitelist

Authorizations:
Request Body schema: application/json
ROTPublicUIDs
required
Array of strings


The list of (1 to N) ROTPublicUIDs that need to be added.

IMEIs
Array of strings


The list of (1 to N) IMEIs that need to be added.

Action
string
Enum: "ADD" "DELETE"

Flag to show whether to add give device in the whitelist or remove it from the whitelist.

Responses

Request samples

Content type
application/json
{
  • "ROTPublicUIDs": [
    ],
  • "Action": "ADD"
}

Response samples

Content type
application/json
{
  • "Message": "Bad Request"
}

/device/whitelist/get

The API call to get list of devices that are whitelisted.

Authorizations:
Request Body schema: application/json
PageNumber
integer

Responses

Request samples

Content type
application/json
{
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "DeviceWhitelist": [
    ],
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 1
}

/device/provisioning/set

Set feature authorizations (Local Data Protection, Local Chip-to-Chip Security, Local Chip-to-Chip Security KeyPairing, ZTPV1) and network parameters (Security Heartbeat) on existing devices (i.e. they have already bootstrapped). Provisioning will happen on the devices' next security hearbeat (when devices wakes up and connects to server)

Sets feature authorization and network parameters on the list of devices provided in the request.

Authorizations:
Request Body schema: application/json
ROTPublicUIDs
Array of strings

[conditionally required]
The list of (1 to N) ROTPublicUIDs that need to be updated.
If you provide TagNames as input parameter, this is not required.

TagNames
Array of strings

[conditionally required]
Give a list of tags and provisioning will be set on all ROTPublicUIDs associated with them.
If you provide ROTPublicUIDs as input parameter, this is not required.

required
object

The desired feature authorization properties (enabled/disabled) to be provisioned on the ROTPublicUID list (it includes network parameters).
Note: Only Local Data Protection, Local Chip-to-Chip Security, Local Chip-to-Chip Security KeyPairing, ZTPV1 security services can be updated using this API.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ],
  • "Provisioning": {
    }
}

Response samples

Content type
application/json
{
  • "Message": "Bad Request"
}

/device/provisioning/get

Get feature authorizations (Local Data Protection, Local Chip-to-Chip Security, Local Chip-to-Chip Security Key Pairing, ZTPV1) and network parameters (Security Hearbeat) that are to be set on existing devices (i.e.: they have already bootstrapped).

Authorizations:
Request Body schema: application/json
ROTPublicUIDs
Array of strings

[conditionally required]
The list of (1 to N) ROTPublicUIDs for which provisioning will be retrieved.
If you provide TagNames as input parameter, this is not required.

TagNames
Array of strings

[conditionally required]
Give a list of tags and provisioning info will be retrieved on all ROTPublicUIDs associated with them.
If you provide ROTPublicUIDs as input parameter, this is not required.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

/device/provisioning/delete

Delete feature authorizations and network parameters that are to be set on existing devices (i.e.: they have already bootstrapped), so when a devices next connects, nothing will be applied.

All devices that connected before a call to this API was made will not be affected by this.

Once deleted, Network Parameters (Security Heartbeat) will revert back to its default value.

Authorizations:
Request Body schema: application/json
ROTPublicUIDs
Array of strings

[conditionally required]
The list of (1 to N) ROTPublicUIDs against which provisioning will be deleted.
If you provide TagNames as input parameter, this is not required.

TagNames
Array of strings

[conditionally required]
Give a list of tags and provisioning will be deleted on all ROTPublicUIDs associated with them.
If you provide ROTPublicUIDs as input parameter, this is not required.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Bad Request"
}

Service APIs

/e2e/key/rotate

The API call to rotate keys used in E2E data protection.

Authorizations:
Request Body schema: application/json
ROTPublicUIDs
Array of strings

[conditionally required]
The list of (1 to N) ROTPublicUIDs for which keys need to be rotated.
If you provide TagNames as input parameter, this is not required.

TagNames
Array of strings

[conditionally required]
Give a list of tags, and keys will be rotated on all ROTPublicUIDs associated with them.
If you provide ROTPublicUIDs as input parameter, this is not required.

Type
required
string
Enum: "CONTINUOUS" "AUTOMATIC"

The type of key rotation to use. Continous means every time e2e APIs are called, the key will be rotated. Automatic means the key will be rotated after given number of days, and if e2e APIs are called before it, the same key will be returned.

Days
integer [ 1 .. 30 ]

Number of days after which key will be rotated. Defaults to 7 days if not given.
Notes: 

  1. SecurityHeartbeat value will be adjusted in case number of days to rotate is less than SecurityHeartbeat value.
  2. This is needed only if Type is "AUTOMATIC".

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ],
  • "Type": "AUTOMATIC",
  • "Days": 1
}

Response samples

Content type
application/json
{
  • "Message": "The automatic rotation has been set. The key will be rotated every 1 day. The Security heartbeat has been adjusted to 1 day."
}

/e2e/uplink/symmetrickey/get

The API call to get the symmetric key.

Authorizations:
Request Body schema: application/json
KeyID
required
string

Key identity used to derive a session Key comprising of 14 bytes. The byte array should be formatted as a Hexadecimal String without a ‘0x’ pattern.

KeyLength
integer
Default: 256

The length of the Key to be generated. The Key length can be either 128 or 256. The default length is 256 and this value will be used if the KeyLength parameter is not included in the call.

Responses

Request samples

Content type
application/json
Example
{
  • "KeyID": "1101000005B52001443F8C16C7EC"
}

Response samples

Content type
application/json
{
  • "Key": "oCa2JO0sqs4F4L//fMScNA==",
  • "ROTPublicUID": 2000089282245
}

/e2e/uplink/protectionparameters/get

The API call used to get the E2E decryption parameters.

Authorizations:
Request Body schema: application/json
EncryptedHeader
required
string

How to obtain this value is explained in the supporting AppNote. The first 16 bytes of the encrypted data header which contains the identity vector used to derive the end to end key. The byte array should be formatted as a Hexadecimal String without a ‘0x’ pattern.
Note: For v2, first 12 bytes of the encrypted data header is required.

Responses

Request samples

Content type
application/json
Example
{
  • "EncryptedHeader": "1101000089282257621f7593c47f0000"
}

Response samples

Content type
application/json
Example
{
  • "Nonce": "BbUgA2S3/b938wAA",
  • "MACLength": 128,
  • "CipherSuite": "AES_128_CCM",
  • "Key": "lTZfP2dO5IAXvJT8FlXV5A==",
  • "KIV": "EQEBAIkoIrZnYX4vnjgCCC==",
  • "ROTPublicUID": 2000089282245
}

/e2e/uplink/integrityparameters/get

The API call used to get the E2E integrity parameters.

Authorizations:
Request Body schema: application/json
EncryptedHeader
required
string

How to obtain this value is explained in the supporting AppNote. The byte array should be formatted as a Hexadecimal String without a ‘0x’ pattern.

Responses

Request samples

Content type
application/json
{
  • "EncryptedHeader": "2900000f0008002f312401"
}

Response samples

Content type
application/json
{
  • "MACLength": 128,
  • "CipherSuite": "AES_128_CCM",
  • "AuthenticationKey": "lTZfP2dO5IAXvJT8FlXV5A==",
  • "AuthKeyLength": 128,
  • "KIV": "EQEBAIkoIrZnYX4vnjgCCC==",
  • "ROTPublicUID": 2000089282245
}

/e2e/downlink/protectionparameters/get

The API call used to get the E2E encryption parameters.

Authorizations:
Request Body schema: application/json
ROTPublicUID
required
string

The ROTPublicUID that uniquely identifies the device.

Responses

Request samples

Content type
application/json
{
  • "ROTPublicUID": 2000089282245
}

Response samples

Content type
application/json
{
  • "MACLength": 128,
  • "KeyLength": 128,
  • "CipherSuite": "AES_128_CS1_HMAC_SHA256",
  • "AuthenticationKey": "lTZfP2dO5IAXvJT8FlXV5A==",
  • "AuthKeyLength": 128,
  • "EncryptionKey": "EuPzZxheaAoGAQ/+X2mYbg==",
  • "KIV": "EQEBAIkoIrZnYX4vnjgCCC==",
  • "AESIV": "KgXYZgAAiSgisgADBBBBBB",
  • "ROTPublicUID": 2000089282245
}

/e2e/downlink/integrityparameters/get

The API call used to get the E2E integrity parameters.

Authorizations:
Request Body schema: application/json
ROTPublicUID
required
string

The ROTPublicUID that uniquely identifies the device.

Responses

Request samples

Content type
application/json
{
  • "ROTPublicUID": 2000089282245
}

Response samples

Content type
application/json
{
  • "MACLength": 128,
  • "CipherSuite": "AES_128_CS1_HMAC_SHA256",
  • "AuthenticationKey": "lTZfP2dO5IAXvJT8FlXV5A==",
  • "AuthKeyLength": 128,
  • "KIV": "EQEBAIkoIrZnYX4vnjgCCC==",
  • "ROTPublicUID": 2000089282245
}

Information APIs

/device/info/get

The API call used to get the aggregated information about the device including:

  1. ROT - The Sealed information
  2. Provisioning State (desired properties, current properties)
Authorizations:
Request Body schema: application/json
ROTPublicUIDs
Array of strings

[conditionally required]
A list of Unique Identifiers (RotPublicUID) that are used to uniquely identify the device.
If you provide TagNames or DeviceSerialNumbers as input parameter, this is not required.

TagNames
Array of strings

[conditionally required]
Give a list of tags and all ROTPublicUIDs associated with them will be used to get device info.
If you provide ROTPublicUIDs or DeviceSerialNumbers as input parameter, this is not required.

DeviceSerialNumbers
Array of strings

[conditionally required]
Give a list of DeviceSerialNumbers and all ROTPublicUIDs associated with them will be used to get device info.
If you provide ROTPublicUIDs or TagNames as input parameter, this is not required.

Options
Array of strings
Items Enum: "CORE" "PROVISIONING" "ZTP"

To control which set of information will be returned. Current values are:

  1. CORE: only ROT related information will be returned
  2. PROVISIONING: desired properties (what needs to be applied on the device), and current properties (what is applied on the device)
  3. ZTP: only device certificate related information will be returned.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ],
  • "Options": [
    ]
}

Response samples

Content type
application/json
{
  • "DeviceInfo": [
    ]
}

/notification/get

The API call to get device notifications. Whenever a device bootstraps (its INFO changes), or some properties get applied on the device, a notification is received, which can be retrieved using this API.

Authorizations:
Request Body schema: application/json
FromDate
required
string

Starting date in ISO 8601 standard. Go back to this date and get notifications that came in after. . You can only specify FromDate as old as 180 days ago.

ToDate
string

End date in ISO 8601 standard. Get notifications till this date.

ROTPublicUIDs
Array of strings

[conditionally required]
Notifications will be retrieved for given ROTPublicUIDs.
Note: If TagNames are given, this is not required.

TagNames
Array of strings

[conditionally required]
Notifications will be retrieved for given ROTPublicUIDs that are assigned given tags.
Note: If ROTPublicUIDs are given, this is not required.

NotificationType
string

Get only this type of notification. Possible values are:

  1. DEVICE_STATE_CHANGE
  2. DEVICE_INFO_CHANGE
  3. DEVICE_PROPERTIES_CHANGE
  4. DEVICE_ERROR

PageNumber
number

Defaults to 1 if not given

Responses

Request samples

Content type
application/json
Example
{
  • "FromDate": "2020-02-01T00:00:00+00:00",
  • "ToDate": "2020-03-01T23:59:00+00:00",
  • "ROTPublicUIDs": [
    ],
  • "NotificationType": "DEVICE_INFO_CHANGE"
}

Response samples

Content type
application/json
{
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 153,
  • "Notifications": [
    ]
}

/device/clone/get

The API call to verify if a particular device or list of devices are cloned or not.

Authorizations:
Request Body schema: application/json
FromDate
required
string

Starting date in ISO 8601 standard. Go back to this date and get devices that cloned after.

ToDate
string

End date in ISO 8601 standard. Get cloned devices till this date.

ROTPublicUIDs
Array of strings

[conditionally required]
Following ROTPublicUIDs will be checked.
Note: If TagNames or DeviceProfileUID is given, this is not required.

TagNames
Array of strings

[conditionally required]
Following ROTPublicUIDs that are assigned given tags will be checked for cloned status.
Note: If ROTPublicUIDs or DeviceProfileUID is given, this is not required.

DeviceProfileUID
string

[conditionally required]
This is the DeviceProfileUID used to logically group a number of devices - the DeviceProfileUID is sealed into each of the devices to be included in the group.

For instances where the DeviceProfileUID was not sealed during the initial bootstrap the value for this parameter is set to: UNATTRIBUTED DEVICE PROFILE.

The DeviceProfileUID can be sealed after bootstrap (known as Two stage bootstrap) - the sealed value will now be returned.

If you provide TagNames as input parameter, this is not required.

Note: Please see the supporting AppNote for information on:

  1. How to seal the DeviceProfileUID.
  2. Two stage bootstrap.
Note: If ROTPublicUIDs or TagNames are given, this is not required.
PageNumber
number

Defaults to 1 if not given

Responses

Request samples

Content type
application/json
Example
{
  • "FromDate": "2020-02-01T00:00:00+00:00",
  • "ToDate": "2020-03-01T23:59:00+00:00",
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 153,
  • "ClonedEvents": [
    ]
}

/device/suspicious/get

The API call to verify if a particular device or list of devices are suspicious or not.

Reasons for a suspicous device are mentioned below.

  1. DUPLICATED_SCL_SERIAL_NUM_SEALED_INFO= Multiple RoTs have been sealed with the same SCL Context Serial Number
  2. DUPLICATED_DEV_SERIAL_NUM_SEALING= multiple RoTs have been sealed with the same Device Serial Number. Remember that Device serial number shall be unique
  3. DUPLICATED_SCL_SERIAL_NUM_PROD_LOG= multiple RoTs have the same SCL Context Serial Number in production logs
  4. DUPLICATED_DEV_SERIAL_NUM_PROD_LOG= When multiple RoTs have the same Device Serial Number in production logs. This scenario can be identified only if the customer provides the production logs
Authorizations:
Request Body schema: application/json
ROTPublicUIDs
Array of strings

[conditionally required]
Following ROTPublicUIDs will be checked.
Note: If TagNames or DeviceProfileUID is given, this is not required.

TagNames
Array of strings

[conditionally required]
Following ROTPublicUIDs that are assigned given tags will be checked for cloned status.
Note: If ROTPublicUIDs or DeviceProfileUID is given, this is not required.

DeviceProfileUID
string

[conditionally required]
This is the DeviceProfileUID used to logically group a number of devices - the DeviceProfileUID is sealed into each of the devices to be included in the group.

For instances where the DeviceProfileUID was not sealed during the initial bootstrap the value for this parameter is set to: UNATTRIBUTED DEVICE PROFILE.

The DeviceProfileUID can be sealed after bootstrap (known as Two stage bootstrap) - the sealed value will now be returned.

If you provide TagNames as input parameter, this is not required.

Note: Please see the supporting AppNote for information on:

  1. How to seal the DeviceProfileUID.
  2. Two stage bootstrap.
Note: If ROTPublicUIDs or TagNames are given, this is not required.
PageNumber
number

Defaults to 1 if not given

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 153,
  • "SuspiciousDevices": [
    ]
}

/device/activity/get

The API call to get device activities - most specifically, commands that were executed / carried out on the device when interacting with server.

Authorizations:
Request Body schema: application/json
FromDate
required
string

Starting date in ISO 8601 standard. Go back to this date and get notifications that came in after.

ToDate
string

End date in ISO 8601 standard. Get notifications till this date.

ROTPublicUID
required
string

Notifications will be retrieved for given ROTPublicUID.

PageNumber
number

The page number that corresponds to the data set intended.

Responses

Request samples

Content type
application/json
{
  • "FromDate": "2020-02-01T00:00:00+00:00",
  • "ToDate": "2020-03-01T23:59:00+00:00",
  • "ROTPublicUID": "0000200456789544",
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 1,
  • "LastSeen": "2020-03-02T07:40:19Z",
  • "Activities": [
    ]
}

/device/usage/get

The API call to get usage logs, aggregated by device (ROTPublicUID). There is a 5 minute lead time before logs get updated. A usage log is generated when following APIs are called:

  1. /e2e/uplink/symmetrickey/get
  2. /e2e/uplink/protectionparameters/get
  3. When you enable "LocalDPR" (Local Data Protection) and it gets applied on the device
  4. When you enable "LocalC2C" (Local Chip-to-Chip Security) and it gets applied on the device
  5. When you enable "LocalC2CKeyPairing" (Local Chip-to-Chip Security Key Pairing) and it gets applied on the device
  6. When you enable "ZTPV1" and it gets applied on the device
  7. When ZTP device certificate is renewed
  8. When ZTP device certificate is updated
Authorizations:
Request Body schema: application/json
FromDate
required
string

To get usage logs from this date. Format of the date is yyyy-mm-dd. You can only specify FromDate as old as 60 days ago.

ToDate
string

To get usage logs till this date. Format of the date is yyyy-mm-dd. If this is not specified, it defaults to today's date.

ROTPublicUIDs
Array of strings

Filter usage logs of given ROTPublicUIDs.

If you provide both TagNames and ROTPublicUIDs as input parameter, it will result in bad request.

TagNames
Array of strings

Filter usage logs of ROTPublicUIDs that have given tags assigned to them.

If you provide both TagNames and ROTPublicUIDs as input parameter, it will result in bad request.

Responses

Request samples

Content type
application/json
Example
{
  • "FromDate": "2020-02-01"
}

Response samples

Content type
application/json
{
  • "2000089282256": {
    }
}

/device/rotpublicuid/get

Lists the ROTPublicUIDs linked to a DeviceProfileUID.

You can also list ROTPublicUIDs by giving a list of tags.

This API returns a paginated response, which means in order to get to next set of records, you would have to give PageNumber in request body.

Authorizations:
Request Body schema: application/json
DeviceProfileUID
string

[conditionally required]
This is the DeviceProfileUID used to logically group a number of devices - the DeviceProfileUID is sealed into each of the devices to be included in the group.

For instances where the DeviceProfileUID was not sealed during the initial bootstrap the value for this parameter is set to: UNATTRIBUTED DEVICE PROFILE.

The DeviceProfileUID can be sealed after bootstrap (known as Two stage bootstrap) - the sealed value will now be returned.

If you provide TagNames as input parameter, this is not required.

Note: Please see the supporting AppNote for information on:

  1. How to seal the DeviceProfileUID.
  2. Two stage bootstrap.
TagNames
Array of strings

[conditionally required]
Give a list of tags and all ROTPublicUIDs associated with them will be returned.
If you provide DeviceProfileUID as input parameter, this is not required.

PageNumber
number

Defaults to 1 if not given

Responses

Request samples

Content type
application/json
Example
{
  • "DeviceProfileUID": "mbYbAX-CoEqE97TMFBsUKQ",
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "ROTPublicUIDs": [
    ],
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 300
}

/apiversion

The API call to get current API version.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "Version": "1.1.1"
}

Zero Touch Provisioning APIs

/ztp/rootca/create

The API call to create a Root CA, which will be used by the server to generate device specific certificates. Once generated, this certificate needs to be uploaded to client's server platform.

NOTES: 

  1. RenewBeforeExpiration field can only be set if Device Certificate Management subscription is active.
  2. Value defined in DeviceCertificateValidity field is subject to change. Because a device certificate is provisioned when device does security heartbeat and validity is then calculated based on Root CA's expiry date. In any case DeviceCertificateValidity cannot be greater than that of Root CA.
  3. RenewBeforeExpiration is subject to security heartbeat and is not an absolute value.
Authorizations:
Request Body schema: application/json
CAName
required
string <= 45 characters

Certificate name
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
CACertificateValidity
required
integer [ 1825 .. 3650 ]

Validity of the certificate, in days. Note: It is highly recommended that validity of the certificate should not be set higher than 3650 days (10 years). Maximum supported value is also 3650 days.

DeviceCertificateValidity
required
integer [ 30 .. 3650 ]

Validity of the certificate generated for the device, in days. Note: It is highly recommended that validity of the certificate should not be set higher than 3650 days (10 years). Maximum supported value is also 3650 days.

RenewBeforeExpiration
integer [ 1 .. 365 ]

Number of days to renew device certificate before it expires.

Responses

Request samples

Content type
application/json
{
  • "CAName": "example.com",
  • "CACertificateValidity": 3650,
  • "DeviceCertificateValidity": 3650,
  • "RenewBeforeExpiration": 180
}

Response samples

Content type
application/json
{
  • "CAName": "example.com",
  • "CACertificateValidity": 1825,
  • "DeviceCertificateValidity": 1825,
  • "Certificate": "-----BEGIN CERTIFICATE-----\\nMIIBzjCCAXWgAwIBAgIIdVrMsEU2rrQwCgYIKoZIzj0EAwIwfDEZMBc1A1UEAwwQ\\nU0lULUlPVC1DSS1UZXN0czERMA8GA1UECgwIS3VkZWxza2kxFTATBgNVBAsMDElv\\nVCBTZWN1cml0A1UELhMsSVNFUCBETSA5YTEwZDgxMy00YWM5LTQ3ODgt\\nYmJjNC1lNzAxOTdlMzZlYjAwHhcNMjAwNDIwMTkwMTA5WhcNMjkwMTA5\\nWjA9MRkwFwYDVQQDDBAwMDAyMDAwMDA1YjUyMDAxMSAwHgYDVQQFExdEZXZpY2Ug\\nOTg3NjU0MzIxYWJjZGVmMjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAWsXezs\\n2hPrm8iYFLlIX5amaKlC7ssZaVJ+Y+FrclfLRwTP9e7BhPWmECXnM7nGBYu0\\nJWn2jH/8VRtIuVWjIDAeMA4GA1UdDwEB/wQwAwIHgDAMBgNVHvOcUEQAQTBmUYbo\\nAiA4gnWnVIqqXQxzo8MohEaYWDZn89aus9W4zIpgApHSWw==\\n-----END CERTIFICATE-----",
  • "CreatedDate": "2020-04-20T19:00:36Z"
}

/ztp/rootca/update

The API allows to set how many days before the certificate expiration, the automatic renewal of the certificate shall take place. Using this procedure the new certificate will use the same key pair as the expiring one, but it will have a new serial number and a new expiration date.

NOTES: 

  1. RenewBeforeExpiration field can only be set if Device Certificate Management subscription is active.
  2. Value defined in DeviceCertificateValidity field is subject to change. Because a device certificate is provisioned when device does security heartbeat and validity is then calculated based on Root CA's expiry date. In any case DeviceCertificateValidity cannot be greater than that of Root CA.
  3. RenewBeforeExpiration is subject to security heartbeat and is not an absolute value.
Authorizations:
Request Body schema: application/json
CAName
required
string <= 45 characters

Certificate name
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
RenewBeforeExpiration
required
integer [ 1 .. 365 ]

Number of days to renew device certificate before it expires.

Responses

Request samples

Content type
application/json
{
  • "CAName": "example.com",
  • "RenewBeforeExpiration": 180
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/ztp/rootca/get

The API call to get a list of created Root CAs or to get a certificate whose certificate name is provided as input.

Authorizations:
Request Body schema: application/json
PageNumber
integer
CAName
string

Certificate name to get

Responses

Request samples

Content type
application/json
{
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "TotalRecords": 10,
  • "PageNumber": 1,
  • "PageSize": 100,
  • "CAs": [
    ]
}

/ztp/rootca/crl/get

The API returns the Certificate Revocation List (CRL) for given Root CAs, that contains the list of all certificates that has been revoked. The output returns a standard CRL string as well as serial numbers of revoked device certificates.

NOTES: 

  1. This API can only be called if Device Certificate Management subscription is active.

Authorizations:
Request Body schema: application/json
CANames
Array of strings

List of root certificate names

Responses

Request samples

Content type
application/json
{
  • "CANames": [
    ]
}

Response samples

Content type
application/json
{
  • "CRLs": [
    ]
}

/ztp/rootca/device/get

The API provides in output the a list of devices (with the ROTPublicUIDs) that have been provisioned with a device certificate signed by a given Root CA.

Authorizations:
Request Body schema: application/json
PageNumber
integer
CAName
required
string

Certificate name against which to get list of devices

Responses

Request samples

Content type
application/json
{
  • "CAName": "acme.example.com"
}

Response samples

Content type
application/json
{
  • "TotalRecords": 1,
  • "PageNumber": 1,
  • "PageSize": 100,
  • "Devices": [
    ]
}

/ztp/rootca/popcertificate/generate

The API call to generate a Proof-of-Possession certificate. Once you upload Root CA to your server, a registration code is generated. Use this registration code to generate a Proof-of-Possession certificate using this API, and upload generated certificate to prove ownership of Root CA that was initially uploaded to server.

Authorizations:
Request Body schema: application/json
CAName
required
string

Certificate name, which was generated earlier.

RegistrationCode
required
string

Registration Code generated by the server where Root CA was uploaded.

Responses

Request samples

Content type
application/json
{
  • "CAName": "example.com",
  • "RegistrationCode": "930783746273459058465786283467236543874968549"
}

Response samples

Content type
application/json
{
  • "CAName": "example.com",
  • "PoPCertificate": "-----BEGIN CERTIFICATE-----\\nMIIBzjCCAXWgAwIBAgIIdVrMsEU2rrQwCgYIKoZIzj0EAwIwfDEZMBc1A1UEAwwQ\\nU0lULUlPVC1DSS1UZXN0czERMA8GA1UECgwIS3VkZWxza2kxFTATBgNVBAsMDElv\\nVCBTZWN1cml0A1UELhMsSVNFUCBETSA5YTEwZDgxMy00YWM5LTQ3ODgt\\nYmJjNC1lNzAxOTdlMzZlYjAwHhcNMjAwNDIwMTkwMTA5WhcNMjkwMTA5\\nWjA9MRkwFwYDVQQDDBAwMDAyMDAwMDA1YjUyMDAxMSAwHgYDVQQFExdEZXZpY2Ug\\nOTg3NjU0MzIxYWJjZGVmMjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAWsXezs\\n2hPrm8iYFLlIX5amaKlC7ssZaVJ+Y+FrclfLRwTP9e7BhPWmECXnM7nGBYu0\\nJWn2jH/8VRtIuVWjIDAeMA4GA1UdDwEB/wQwAwIHgDAMBgNVHvOcUEQAQTBmUYbo\\nAiA4gnWnVIqqXQxzo8MohEaYWDZn89aus9W4zIpgApHSWw==\\n-----END CERTIFICATE-----"
}

/ztp/rootca/delete

The API call to delete a Root CA.

NOTES: 

  1. The Root CA cannot be deleted if it is set either in current or desired properties of a device.
  2. If Root CA is linked to a device profile, Root CA cannot be deleted.

Authorizations:
Request Body schema: application/json
CAName
required
string

Name of the certificate.

Responses

Request samples

Content type
application/json
{
  • "CAName": "example.com"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/ztp/devicecertificate/renew

This API shall be used to renew manually the device certificate instead of using the automatic procedure that is triggered by /ztp/rootca/update for all the device certificates signed by the given Root CA. Using this procedure the new certificate will use the same key pair as the expiring one, but it will have a new serial number and a new expiration date.

NOTES: 

  1. This API can only be called if Device Certificate Management subscription is active and quota for given ROTPublicUIDs is not exceeded.
  2. Value defined in DeviceCertificateValidity field is subject to change. Because a device certificate is provisioned when device does security heartbeat and validity is then calculated based on Root CA's expiry date. In any case DeviceCertificateValidity cannot be greater than that of Root CA.
  3. This API cannot be called if /ztp/devicecertificate/update API was called and device certificate update process is still on-going.
Authorizations:
Request Body schema: application/json
CAName
required
string <= 45 characters

Certificate name
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
DeviceCertificateValidity
required
integer [ 30 .. 3650 ]

Validity of the certificate generated for the device, in days. Note: It is highly recommended that validity of the certificate should not be set higher than 365 days (1 year). Maximum supported value is also 3650 days (10 years).

ROTPublicUIDs
Array of strings

[conditionally required]
An array of ROTPublicUIDs whose certificates will be renewed.
Note: If SerialNumbers is given, this is not required.

SerialNumbers
Array of strings

[conditionally required]
An array of SerialNumbers whose certificates will be renewed.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ],
  • "CAName": "example.com",
  • "DeviceCertificateValidity": 1000
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/ztp/devicecertificate/update

This API shall be used to renew manually the device certificate for all the devices listed. Using this procedure the new certificate will use a new set of key pair and it will have a new serial number and a new expiration date.

This will happen in two security heartbeats, which means when the device first sends a heartbeat, the existing device certificate will be removed, and when the device sends a second heartbeat, a new device certificate (with same root CA but different key/pair) will be provisioned on the device.

NOTES: 

  1. A manual secure heartbeat event can be triggered as well to expedite the process.
  2. This API can only be called if Device Certificate Management subscription is active and quota for given ROTPublicUIDs is not exceeded.
  3. When a device certificate is updated, its validity is subject to Root CA's validity and will not exceed Root CA's expiry date.
Authorizations:
Request Body schema: application/json
CAName
required
string <= 45 characters

Certificate name
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
ROTPublicUIDs
Array of strings

[conditionally required]
An array of ROTPublicUIDs whose certificates will be renewed.
Note: If SerialNumbers is given, this is not required.

SerialNumbers
Array of strings

[conditionally required]
An array of SerialNumbers whose certificates will be renewed.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUIDs": [
    ],
  • "CAName": "example.com"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/ztp/devicecertificate/delete

This API shall be used to completely remove the device certificate and key pair from the device at the next security heartbeat.

NOTES: 

  1. This API can only be called if Device Certificate Management subscription is active and quota for given ROTPublicUIDs is not exceeded.
  2. This API cannot be called if /ztp/devicecertificate/update API was called and device certificate update process is still on-going.

Authorizations:
Request Body schema: application/json
ROTPublicUIDs
required
Array of strings


An array of ROTPublicUIDs whose device certificate is to be deleted.

Responses

Request samples

Content type
application/json
{
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/ztp/devicecertificate/revoke

This API shall be used to revoke the validity of the device certificate immediately. This results in a new entry for the device certificate in the Certificate Revocation List, but does not cause the removal of the certificate from the device. If you want to remove the certificate you need to use the proper API. Also, if your IoT platform is not able to use the CRL, you need to deactivate/delete the certificate in the IoT platform.

NOTES: 

  1. This API can only be called if Device Certificate Management subscription is active and quota for given ROTPublicUIDs is not exceeded.
  2. This API cannot be called if /ztp/devicecertificate/update API was called and device certificate update process is still on-going.

Authorizations:
Request Body schema: application/json
CAName
required
string <= 45 characters

Certificate name
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
ROTPublicUID
string

[conditionally required]
A ROTPublicUID whose device certificate will be revoked.
Note: If SerialNumber is given, this is not required.

SerialNumber
string

[conditionally required]
A SerialNumber of device certificate to be revoked.

Responses

Request samples

Content type
application/json
Example
{
  • "ROTPublicUID": "0002000089280087",
  • "CAName": "example.com"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/ztp/devicecertificate/rootca/transfer

This API call can be used to transfer the device certificate from one Root CA to another, for example if you use two different Root CAs for test and production. After the device security heartbeat is performed the old device certificate is replaced with the new one signed by the target Root CA.

NOTES: 

  1. This API can only be called if Device Certificate Management subscription is active and quota for given ROTPublicUIDs is not exceeded.
  2. When a device certificate is transfered, its validity is subject to new Root CA's validity and will not exceed Root CA's expiry date.
  3. This API cannot be called if /ztp/devicecertificate/update API was called and device certificate update process is still on-going.

Authorizations:
Request Body schema: application/json
FromCA
required
string <= 45 characters

Existing Root CA name of the device
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
ToCA
required
string <= 45 characters

Target Root CA
Note:

  • It has to be publically unique
  • It can only contain
    • alphabets
    • numbers
    • underscores
    • dashes
    • dots
ROTPublicUIDs
required
Array of strings

An array of ROTPublicUIDs whose Root CA will be transferred.

Responses

Request samples

Content type
application/json
{
  • "ROTPublicUIDs": [
    ],
  • "FromCA": "examplefrom.com",
  • "ToCA": "exampleto.com"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

Notification Hook APIs

/notification/webhook/create

The API call to create a notification hook against a given notification event type. This will enable users to setup their own API endpoints, which will be called when a notification is generated, and incoming notification data will be passed on (as JSON request body) to this API endpoint.

Authorizations:
Request Body schema: application/json
NotificationURL
required
string

Fully qualified URL to call (only https endpoints are accepted). You can register multiple notification URLs against a specific notiifcation event type.

AuthorizationToken
required
string

Authorization token to set in "Authorization" header of the request when calling notification URL.

NotificationType
required
string

The type of notification event for which this notification URL will be called. Possible values are:

  1. DEVICE_BOOTSTRAP_EVENT

    This event gets fired whenever a device bootstraps (registers) with the server. As soon as the device is saved in our system, we send bootstrap info to this event. Subscribe to this event if you want to keep track of device bootstraps. An example of bootstrap payload is:

    { "ROTPublicUID": "135700008928c093", "Timestamp": "2020-05-07T11:23:32", "EventType": "DEVICE_BOOTSTRAP_EVENT", "Payload": { "RotVersion": "1", "SerialNumber": "235435", "Version": "12", "DeviceSerialNumber": "123234354", "IMEI": "862618583984360", "DeviceProfileUID": "QHlN732VgUWCdfNeXHkQR1", "TypeNumber": "SARA-R410M-03B-00", "IsBlacklisted": false } }


  2. DEVICE_PROPERTIES_CHANGE_EVENT

    This event gets fired when device's properties change. When you call provisioning APIs to set "desired" properties for a device, this event is triggered when those "desired" properties are applied to the device, and become "current" properties. Subscribe to this event if you want to keep track of device properties changes. An example of properties payload is:

    { "ROTPublicUID": "135700008928b093", "Timestamp": "2020-05-09T00:10:15", "EventType": "DEVICE_PROPERTIES_CHANGE_EVENT", "Payload": { "DesiredProperties": { "Authorizations": [ {"Name": "LocalDPR", "State": "ENABLED","ModifiedDate": "2020-04-25T06:22:12+00:00" } ] },"CurrentProperties": { "Authorizations": [{"Name": "LocalDPR", "State": "ENABLED", "SyncDate": "2020-02-12T06:22:14+00:00" } ] }}}

    Properties that can change, and can trigger this event are:

    1. Authorizations:
      1. LocalDPR
      2. LocalC2C
      3. LocalC2CKeyPairing
      4. ZTPV1
      5. Evaluation
    2. Network Parameters
    3. Zerotouch


  3. DEVICE_ERRORS_EVENT

    This event gets fired whenever a device error is encountered. For whatever reason, if the server is unable to communicate with the device or if the device fails to act on a command from the server, this event gets fired. Subscribe to this event if you want to keep track of device error changes. An example of error payload is:

    {"ROTPublicUID": "135700008928c093", "EventType": "DEVICE_ERRORS_EVENT", "Timestamp": "2020-05-10T19:39Z","Payload":{"Error": "Invalid KeySetId for device" }}


  4. DEVICE_CERTIFICATE_RENEWAL_EVENT

    This event gets fired whenever a device certificate gets renewed. An example of payload is:

    {"ROTPublicUID": "135700008928c093", "EventType": "DEVICE_CERTIFICATE_RENEWAL_EVENT", "Timestamp": "2020-05-10T19:39Z","Payload":{"CertificateAuthorityName": "eaxample.com","CertificateSerialNumber":"73068c914de40ccaee84e03a66b4858","CertificateValidity":1825,"ExpirationDate":"2020-05-10T19:39Z" }}


  5. DEVICE_CERTIFICATE_EXPIRATION_EVENT

    This event gets fired at 60 days before, 30 days before, 7 days before expiration. An example of payload is:

    {"ROTPublicUID": "135700008928c093", "EventType": "DEVICE_CERTIFICATE_EXPIRATION_EVENT", "Timestamp": "2020-05-10T19:39Z","Payload":{"CertificateAuthorityName": "eaxample.com","CertificateSerialNumber":"73068c914de40ccaee84e03a66b4858","DaysToExpiration":60,"ExpirationDate":"2020-05-10T19:39Z" }}


  6. ROOTCA_EXPIRATION_EVENT

    This event gets fired at 180, 90, 60, 30, 7, 0 days before expiration. An example of payload is:

    {"EventType": "ROOTCA_EXPIRATION_EVENT", "Timestamp": "2020-05-10T19:39Z","Payload":{"CertificateAuthorityName": "test-ca",
    "DaysToExpiration": 60, "ExpirationDate": "2020-09-20T09:52:58", "ProvisionedDevicesCount": 6 }}


Responses

Request samples

Content type
application/json
{
  • "NotificationURL": "https://example.com",
  • "AuthorizationToken": "Bearer eiuytreuihkjfghdlyreuiyt",
  • "NotificationType": "DEVICE_BOOTSTRAP_EVENT"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/notification/webhook/update

The API call to update a notification hook. This API can be used to update AuthorizationToken for a given notification URL.

Authorizations:
Request Body schema: application/json
NotificationURL
required
string

A fully qualified URL

AuthorizationToken
required
string

Authorization token to set in "Authorization" header of the request when calling notification URL.

Responses

Request samples

Content type
application/json
{
  • "NotificationURL": "https://example.com",
  • "AuthorizationToken": "Bearer eiuytreuihkjfghdlyreuiyt"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/notification/webhook/delete

The API call to delete an already created notification hook.

Authorizations:
Request Body schema: application/json
NotificationURL
required
string

A fully qualified URL

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/notification/webhook/get

The API call to get a list of all created notification hooks.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Tag APIs

/tag/create

The API call to create a tag. Once a tag is created, it can then be used in other APIs (that support tags).

Authorizations:
Request Body schema: application/json
TagName
required
string

It can:

  • Consist of alphabets, numbers, and symbols. Following symbols are not allowed:
    • ^
    • `
    • ~
    • <
    • >
    • "
    • {
    • }
    • |

    • ,
  • Can only be 255 characters long
  • Is case-insensitive

Responses

Request samples

Content type
application/json
{
  • "TagName": "downtown"
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}

/tag/delete

The API call to delete an already created tag. Only those tags can be deleted that aren't assigned to any ROTPublicUIDs. If a tag is assigned to ROTPublicUIDs, it must first be unassigned from all assigned ROTPublicUIDs and then can be deleted.

Authorizations:
Request Body schema: application/json
TagName
required
string

Tag name to delete

Responses

Request samples

Content type
application/json
{
  • "TagName": "downtown"
}

Response samples

Content type
application/json
{
  • "message": "Request aborted. This tag is currently assigned to ROTPublicUID(s)"
}

/tag/get

The API call to get a list of all created tags.

Authorizations:
Request Body schema: application/json
PageNumber
integer

Defaults to 1 if not given.

Responses

Request samples

Content type
application/json
{
  • "PageNumber": 1
}

Response samples

Content type
application/json
{
  • "Tags": [
    ],
  • "PageNumber": 1,
  • "PageSize": 100,
  • "TotalRecords": 1
}

/tag/assign

The API call to assign tags to ROTPublicUIDs. Every given tag will be assigned to every given ROTPublicUID.

Authorizations:
Request Body schema: application/json
TagNames
required
Array of strings

An array of tag names that need to be assigned to ROTPublicUIDs.

ROTPublicUIDs
Array of strings

[conditionally required]
An array of ROTPublicUIDs that would be assigned mentioned tags.
Note: If DeviceProfileUIDs is given, this is not required.

DeviceProfileUIDs
Array of strings

[conditionally required]
An array of DeviceProfileUIDs that would be assigned mentioned tags.

SyncRequired
boolean

Responses

Request samples

Content type
application/json
Example
{
  • "TagNames": [
    ],
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "message": "Bad Request. Invalid ROTPublicUIDs"
}

/tag/remove

The API call to remove tags from ROTPublicUIDs. Every given tag will be removed from every given ROTPublicUID - if a particular combination of TagName and ROTPublicUID doesn't exist, nothing will happen and the combination will be ignored.

It is possible to remove tags from all assigned ROTPublicUIDs, and vice versa.

Authorizations:
Request Body schema: application/json
TagNames
required
Array of strings

An array of tag names that need to be removed from ROTPublicUIDs.
Note: If {*} is given, it would remove all associated tags from given ROTPublicUIDs or DeviceProfileUIDs.

ROTPublicUIDs
Array of strings

[conditionally required]
An array of ROTPublicUIDs that would no longer be associated with mentioned tags.
Notes:

  1. If {*} is given, it would remove all associated ROTPublicUIDs from given tags.
  2. If DeviceProfileUIDs are not given, this is not required.

DeviceProfileUIDs
Array of strings

[conditionally required]
An array of DeviceProfileUIDs that would no longer be associated with mentioned tags.
Notes:

  1. If {*} is given, it would remove all associated DeviceProfileUIDs from given tags.
  2. If ROTPublicUIDs are not given, this is not required.

SyncRequired
boolean

Responses

Request samples

Content type
application/json
Example
{
  • "TagNames": [
    ],
  • "ROTPublicUIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Not Authorized."
}