Version: 2.0

Cloud Nodes

Introduction

Cloud nodes acts as gateways to the PDK cloud platform. One or more cloud nodes can be synced with a system, and each cloud node usually represents a distinct geographic location. You can learn more about the PDK topology here. Note that the API sometimes refers to cloud nodes as panels.

The cloud node object

{
  "id": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
  "name": "Test Cloud Node",
  "description": null,
  "created": "2023-09-27T22:21:56.671Z",
  "serialNumber": "1234ABC",
  "ecards": [1234567],
  "offlinePolicy": 1,
  "killTimer": 259200,
  "timezone": "US/Pacific",
  "locale": "en",
  "cardFormat": [
    {
      "id": "d057fbaa-aa27-4905-a5af-7b610e5cc83f",
      "description": "Standard 26-bit Format",
      "min_input_bits": 9,
      "max_input_bits": 64,
      "enfore_parity": false,
      "facility_code": "NOT_ENFORCED"
    }
  ],
  "syncStatus": {
    "synced": false,
    "details": {
      "timestamp": "2023-10-31T14:32:51.281Z",
      "dataFlowStatus": "Started"
    }
  },
  "connectionStatus": {
    "connected": true,
    "details": {
      "timestamp": "2023-09-27T22:55:12Z"
    }
  }
}

Property	Type	Description
`id`	String	The cloud node ID.
`name`	String	The cloud node name.
`description`	String	The cloud node description.
`created`	String	An ISO 8601 timestamp representing the time at which the cloud node was registered.
`serialNumber`	String	The cloud node serial number.
`ecards`	Integer[]	An array of emergency card (e-card) numbers.
`offlinePolicy`	Integer	How the cloud node behaves if it's offline and unable to acquire the current time. `0` means only users with e-cards will be allowed, `1` means only users with 24×7 access will be allowed, and `2` means all users with credentials will be allowed, regardless of the time (i.e. schedules will be ignored).
`killTimer`	Integer	The amount of time (in seconds) the cloud node is allowed to remain offline before reverting to emergency card (e-card) access only.
`timezone`	String	The cloud node time zone in TZ notation.
`locale`	String	An ISO 639-1 language code representing the preferred language for the cloud node.
`cardFormat`	Object[]	An array of allowed card formats.
`cardFormat.id`	String	The card format ID.
`cardFormat.description`	String	The card format description.
`cardFormat.min_input_bits`	Integer	The minimum number of bits allowed in the data packet transmitted by the reader.
`cardFormat.max_input_bits`	Integer	The maximum number of bits allowed in the data packet transmitted by the reader.
`cardFormat.facility_code`	String	How facility codes are enforced. `ENFORCED` means facility codes are enforced on a per-credential basis, `FILTER_LIST` means only the facility codes specified in the `allowed_facility_codes` parameter are allowed, and `NOT_ENFORCED` means facility codes are ignored.
`cardFormat.allowed_facility_codes`	Integer[]	An array of allowed facility codes. This only applies if `facility_code` is set to `FILTER_LIST`.
`cardFormat.enforce_parity`	Boolean	Whether credential scans are denied if their parity doesn't match.
`syncStatus.synced`	Boolean	Whether or not the cloud node is synced with the system.
`syncStatus.details.timestamp`	String	An ISO 8601 timestamp representing the last time the cloud node synced with the system.
`syncStatus.details.dataFlowStatus`	String	A description of the sync status. This only applies if `synced` is `false`. Possible values include `Pending`, `Started`, `BlockedByOfflineNode`, and `BlockedByFailure`.
`connectionStatus.connected`	Boolean	Whether or not the cloud node is connected.
`connectionStatus.details.timestamp`	String	An ISO 8601 timestamp representing the last time the connection status was updated.

info

If a cloud node is offline but no changes have been made to the system since the last sync, then syncStatus.synced will still be true even if connectionStatus.connected is false.

Basic Endpoints

Create a cloud node

Request

POST https://systems.pdk.io/{{system_id}}/cloud-nodes HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Cloud Node"
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`system_token`	Header	String	Yes	A valid system token.
`name`	Body	String	Yes	The cloud node name.
`description`	Body	String	No	The cloud node description.
`serialNumber`	Body	String	No	The cloud node serial number.
`ecards`	Body	Integer[]	No	An array of emergency card (e-card) numbers.
`offlinePolicy`	Body	Integer	No	How the system behaves if it's offline and unable to acquire the current time. `0` (default) means only users with e-cards will be allowed, `1` means only users with 24×7 access will be allowed, and `2` means all users with credentials will be allowed, regardless of the time (i.e. schedules will be ignored).
`killTimer`	Body	Integer	No	The amount of time (in seconds) the system is allowed to remain offline before reverting to emergency card (e-card) access only. The minimum value is 300 seconds. The default value is 259200 seconds (3 days).
`timezone`	Body	String	No	The cloud node time zone in TZ notation. The default value is the time zone of the system.
`locale`	Body	String	No	An ISO 639-1 language code representing the preferred language for the cloud node. The default value is `en`.
`cardFormat`	Body	Object[]	No	An array of allowed card formats. The default value includes only the standard 26-bit format.
`cardFormat.id`	Body	String	Yes	The card format ID.
`cardFormat.description`	Body	String	No	The card format description.
`cardFormat.min_input_bits`	Body	Integer	Yes	The minimum number of bits allowed in the data packet transmitted by the reader. The minimum value is 9 and the maximum value is 512.
`cardFormat.max_input_bits`	Body	Integer	Yes	The maximum number of bits allowed in the data packet transmitted by the reader. The minimum value is 9 and the maximum value is 512.
`cardFormat.facility_code`	Body	String	No	How facility codes are enforced. `ENFORCED` (default) means facility codes are enforced on a per-credential basis, `FILTER_LIST` means only the facility codes specified in the `allowed_facility_codes` parameter are allowed, and `NOT_ENFORCED` means facility codes are ignored.
`cardFormat.allowed_facility_codes`	Body	Integer[]	Sometimes	An array of allowed facility codes. This is required if `facility_code` is set to `FILTER_LIST`.
`cardFormat.enforce_parity`	Body	Boolean	No	Whether credential scans should be denied if their parity doesn't match. The default value is `true`.

Response

The response contains the ID of the newly created cloud node object.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "7d829ff4-53e8-4d76-8762-1022ccdeae39"
}

Retrieve a cloud node

Request

GET https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`cloud_node_id`	Path	String	Yes	The cloud node ID.
`system_token`	Header	String	Yes	A valid system token.

Response

The response contains a cloud node object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
  "name": "Test Cloud Node",
  "description": null,
  "created": "2023-09-27T22:21:56.671Z",
  "serialNumber": "1234ABC",
  "ecards": [1234567],
  "offlinePolicy": 1,
  "killTimer": 259200,
  "timezone": "US/Pacific",
  "locale": "en",
  "cardFormat": [
    {
      "id": "d057fbaa-aa27-4905-a5af-7b610e5cc83f",
      "description": "Standard 26-bit Format",
      "min_input_bits": 9,
      "max_input_bits": 64,
      "enfore_parity": false,
      "facility_code": "NOT_ENFORCED"
    }
  ],
  "syncStatus": {
    "synced": true,
    "details": {
      "timestamp": "2024-06-14T15:13:47.000Z"
    }
  },
  "connectionStatus": {
    "connected": true,
    "details": {
      "timestamp": "2023-10-31T14:08:03.000Z"
    }
  }
}

Update a cloud node

Request

PUT https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Cloud Node"
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`cloud_node_id`	Path	String	Yes	The cloud node ID.
`system_token`	Header	String	Yes	A valid system token.
`name`	Body	String	Yes	The cloud node name.
`description`	Body	String	No	The cloud node description.
`serialNumber`	Body	String	No	The cloud node serial number.
`ecards`	Body	Integer[]	No	An array of emergency card (e-card) numbers.
`offlinePolicy`	Body	Integer	No	How the system behaves if it's offline and unable to acquire the current time. `0` (default) means only users with e-cards will be allowed, `1` means only users with 24×7 access will be allowed, and `2` means all users with credentials will be allowed, regardless of the time (i.e. schedules will be ignored).
`killTimer`	Body	Integer	No	The amount of time (in seconds) the system is allowed to remain offline before reverting to emergency card (e-card) access only. The minimum value is 300 seconds. The default value is 259200 seconds (3 days).
`timezone`	Body	String	No	The cloud node time zone in TZ notation. The default value is the time zone of the system.
`locale`	Body	String	No	An ISO 639-1 language code representing the preferred language for the cloud node. The default value is `en`.
`cardFormat`	Body	Object[]	No	An array of allowed card formats. The default value includes only the standard 26-bit format.
`cardFormat.id`	Body	String	Yes	The card format ID.
`cardFormat.description`	Body	String	No	The card format description.
`cardFormat.min_input_bits`	Body	Integer	Yes	The minimum number of bits allowed in the data packet transmitted by the reader. The minimum value is 9 and the maximum value is 512.
`cardFormat.max_input_bits`	Body	Integer	Yes	The maximum number of bits allowed in the data packet transmitted by the reader. The minimum value is 9 and the maximum value is 512.
`cardFormat.facility_code`	Body	String	No	How facility codes are enforced. `ENFORCED` (default) means facility codes are enforced on a per-credential basis, `FILTER_LIST` means only the facility codes specified in the `allowed_facility_codes` parameter are allowed, and `NOT_ENFORCED` means facility codes are ignored.
`cardFormat.allowed_facility_codes`	Body	Integer[]	Sometimes	An array of allowed facility codes. This is required if `facility_code` is set to `FILTER_LIST`.
`cardFormat.enforce_parity`	Body	Boolean	No	Whether credential scans should be denied if their parity doesn't match. The default value is `true`.

Response

HTTP/1.1 204 No Content

Delete a cloud node

Request

DELETE https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`cloud_node_id`	Path	String	Yes	The cloud node ID.
`system_token`	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all cloud nodes

Request

GET https://systems.pdk.io/{{system_id}}/cloud-nodes HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`search`	Query	String	No	A keyword used to filter the results by searching for partial matches against the `name`, `serialNumber`, and `description` properties.
`page`	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
`per_page`	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
`system_token`	Header	String	Yes	A valid system token.

Response

The response contains an array of cloud node objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
    "name": "Test Cloud Node",
    "description": null,
    "created": "2023-09-27T22:21:56.671Z",
    "serialNumber": "1234ABC",
    "ecards": [1234567],
    "offlinePolicy": 1,
    "killTimer": 259200,
    "timezone": "US/Pacific",
    "locale": "en",
    "cardFormat": [
      {
        "id": "d057fbaa-aa27-4905-a5af-7b610e5cc83f",
        "description": "Standard 26-bit Format",
        "min_input_bits": 9,
        "max_input_bits": 64,
        "enfore_parity": false,
        "facility_code": "NOT_ENFORCED"
      }
    ],
    "syncStatus": {
      "synced": true,
      "details": {
        "timestamp": "2023-10-31T14:08:03.000Z"
      }
    },
    "connectionStatus": {
      "connected": true,
      "details": {
        "timestamp": "2023-09-27T22:55:12Z"
      }
    }
  }
]

List all cloud node hardware

Request

GET https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/hardware HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`cloud_node_id`	Path	String	Yes	The cloud node ID.
`system_token`	Header	String	Yes	A valid system token.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "b8f4c2a9-0cdc-40fd-90ac-f1c51a4f524b",
    "type": "controller",
    "connection": {
      "id": "767a1e35-bd34-4858-9130-a0a1900438ed",
      "name": "Test Connection",
      "type": "usb"
    },
    "wirelessAddress": "",
    "firmwareVersion": "1.1.46",
    "hardwareVersion": "red1cn.d",
    "serialNumber": "8003323",
    "connectionStatus": {
      "connected": true,
      "details": {
        "timestamp": "2023-10-04T00:27:07.000Z"
      }
    },
    "radioTimeout": false,
    "overcurrent": false,
    "undervoltage": false,
    "lowPowerMode": false,
    "batteryChargeCategory": "N",
    "batteryHealth": "U",
    "inputPowerOn": true,
    "peripheralPowerOn": true,
    "recentComlosses": [],
    "unstableConnection": false,
    "bootloaderVersion": "1.0.44",
    "startupVersion": "0.3.1",
    "batteryLevel": 0,
    "batteryTime": 0,
    "batteryCurrent": 0,
    "inputVoltage": 13984,
    "inputCurrent": 132,
    "peripheralCurrent": 161,
    "peripheralVoltage": 12096,
    "syncStatus": {
      "synced": true,
      "details": {
        "timestamp": "2023-10-04T15:43:17.000Z"
      }
    },
    "transactions": []
  }
]

Introduction​

The cloud node object​

Basic Endpoints​

Create a cloud node​

Request

Response

Retrieve a cloud node​

Request

Response

Update a cloud node​

Request

Response

Delete a cloud node​

Request

Response

List all cloud nodes​

Request

Response

List all cloud node hardware​

Request

Response

Introduction

The cloud node object

Basic Endpoints

Create a cloud node

Retrieve a cloud node

Update a cloud node

Delete a cloud node

List all cloud nodes

List all cloud node hardware