Version: 2.0

Systems

Introduction

A system defines a unique set of holders, credentials, groups, and rules. These entities can by synced with one or more cloud nodes, where each cloud node represents a distinct geographic location. For example, consider a company with a corporate office in one city and a warehouse in a neighboring city. Each location would require its own cloud node, but some employees may need access to both locations. In this scenario, both cloud nodes could be connected to a single system, allowing holders, credentials, groups, and rules to be shared between them. You can learn more about the PDK topology here.

The system object

{
  "id": "9b9ec144-7276-40bf-9a7c-47d3547314a8",
  "name": "Test System",
  "description": "This is a test description.",
  "ouId": "6539a1d5f362be88d52dc94d",
  "created": "2023-10-25T23:16:37.959Z",
  "reportingPlan": "basic",
  "credentialSelfHelp": {
    "enabled": true,
    "monthlyLimit": 1
  },
  "cloudNodes": [
    {
      "id": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
      "name": "Test Cloud Node",
      "description": null,
      "created": "2023-09-27T22:21:56.671Z",
      "serialNumber": "1234ABC"
    }
  ],
  "locale": "en",
  "timezone": "UTC",
  "cardFormat": {
    "id": "234dbdbf-cf29-4b0b-ba4f-acac68274ba8",
    "description": "Standard 26-bit Format",
    "min_input_bits": 9,
    "max_input_bits": 64,
    "facility_code": "NOT_ENFORCED"
  },
  "offlinePolicy": 1,
  "killTimer": 259200,
  "syncStatus": {
    "synced": true,
    "details": {
      "timestamp": "2023-10-31T14:08:03.000Z"
    }
  }
}

Property	Type	Description
`id`	String	The system ID.
`name`	String	The system name.
`description`	String	The system description.
`ouId`	String	The ID of the organization associated with the system.
`created`	String	An ISO 8601 timestamp representing the time at which the system was created.
`reportingPlan`	String	The selected reporting plan. Possible values include `basic`, `standard`, and `premium`.
`credentialSelfHelp.enabled`	Boolean	Whether credential self-help is enabled.
`credentialSelfHelp.monthlyLimit`	Integer	The monthly limit for credential self-help resets (if enabled).
`cloudNodes`	Object[]	An array of partial cloud node objects representing the cloud nodes associated with the system.
`locale`	String	An ISO 639-1 language code representing the preferred language for the system. This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`timezone`	String	The system time zone in TZ notation. This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`cardFormat`	Object Object[]	The default card format. This may also be an array of card format objects. This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`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.
`offlinePolicy`	Integer	How the system 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). This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`killTimer`	Integer	The amount of time (in seconds) the system is allowed to remain offline before reverting to emergency card (e-card) access only. The default value is 259200 (3 days). This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`syncStatus.synced`	Boolean	Whether or not the system is synced with its cloud nodes.
`syncStatus.details.timestamp`	String	An ISO 8601 timestamp representing the last time the system synced with its cloud nodes.

Basic Endpoints

info

There is no endpoint for creating a system directly. New systems are created automatically when creating a customer. You can learn more about the PDK topology here.

Retrieve a system

Request

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

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

Response

The response contains a system object.

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

{
  "id": "9b9ec144-7276-40bf-9a7c-47d3547314a8",
  "name": "Test System",
  "description": "This is a test description.",
  "ouId": "6539a1d5f362be88d52dc94d",
  "created": "2023-10-25T23:16:37.959Z",
  "reportingPlan": "basic",
  "credentialSelfHelp": {
    "enabled": true,
    "monthlyLimit": 1
  },
  "cloudNodes": [
    {
      "id": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
      "name": "Test Cloud Node",
      "description": null,
      "created": "2023-09-27T22:21:56.671Z",
      "serialNumber": "1234ABC"
    }
  ],
  "locale": "en",
  "timezone": "UTC",
  "cardFormat": {
    "id": "234dbdbf-cf29-4b0b-ba4f-acac68274ba8",
    "description": "Standard 26-bit Format",
    "min_input_bits": 9,
    "max_input_bits": 64,
    "facility_code": "NOT_ENFORCED"
  },
  "offlinePolicy": 1,
  "killTimer": 259200,
  "syncStatus": {
    "synced": true,
    "details": {
      "timestamp": "2023-10-31T14:08:03.000Z"
    }
  }
}

Update a system

Request

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

{
  "description": "This is a test description.",
  "credentialSelfHelp": {
    "enabled": true,
    "monthlyLimit": 1
  },
  "locale": "en",
  "timezone": "UTC",
  "cardFormat": {
    "id": "234dbdbf-cf29-4b0b-ba4f-acac68274ba8"
  },
  "offlinePolicy": 1,
  "killTimer": 259200
}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`system_token`	Path	String	Yes	A valid system token.
`description`	Body	String	No	The system description.
`credentialSelfHelp.enabled`	Body	Boolean	No	Whether credential self-help should be enabled.
`credentialSelfHelp.monthlyLimit`	Body	Integer	No	The monthly limit for credential self-help resets (if enabled).
`locale`	Body	String	No	An ISO 639-1 language code representing the preferred language for the system. This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`timezone`	Body	String	No	The system time zone in TZ notation. This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`cardFormat`	Body	Object Object[]	No	The default card format. This may also be an array of card format objects. This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`cardFormat.id`	Body	String	Yes	The card format ID.
`offlinePolicy`	Body	Integer	No	How the system should behave 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). This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.
`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 default value is 259200 (3 days). This can be customized for individual cloud nodes, but new cloud nodes will inherit this system setting.

Response

HTTP/1.1 204 No Content

Create a system token

Request

POST https://accounts.pdk.io/api/systems/{{system_id}}/token HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`id_token`	Header	String	Yes	A valid ID token.

Response

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

{
  "token": "..."
}

Search a system

This endpoint allows you to search for holders, groups, and floor groups within a system.

Request

GET https://systems.pdk.io/{{system_id}}/search?q=test HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
`system_id`	Path	String	Yes	The system ID.
`system_token`	Header	String	Yes	A valid system token.
`q`	Query	String	Yes	A case-insensitive search query.

Response

The response contains an array of results.

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

[
  {
    "id": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
    "type": "holder",
    "name": "John Wiegand",
    "image": "http://systems.pdk.io/images/2327fe80-62cf-11ee-8ebd-ad4ed315003b"
  },
  {
    "id": "b3c431d1-aa64-4b74-aa20-65575b17b557",
    "type": "group",
    "name": "Test Group"
  }
]

Parameter	Type	Description
`id`	Integer	The ID of the entity.
`type`	String	The entity type. Possible values include `holder`, `group`, and `floor group`.
`name`	String	The name of the entity.
`image`	String	The url of the holder's photo. This only applies if `type` is set to `holder`.

Retrieve the status of a system

Request

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

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

Response

{
  "elevatorsPresent": false,
  "facilityCodes": "supported",
  "cloudNodes": [
    {
      "serialNumber": "1234ABC",
      "id": "0becb612-2830-4fca-8c44-f3db11234443",
      "name": "Test Cloud Node",
      "hardware": [
        {
          "id": "7ac5d3ff-63ba-4f4b-98f7-543423123",
          "type": "controller",
          "connection": {
            "id": "1d761b69-a25d-4ce6-ad5e-7112344ww2",
            "name": "Test Connection",
            "type": "usb"
          },
          "wirelessAddress": "",
          "firmwareVersion": "2.0.17",
          "hardwareVersion": "red1cn.1c",
          "serialNumber": "8013242",
          "connectionStatus": {
            "connected": true,
            "details": {
              "timestamp": "2024-05-13T14:48:34.000Z"
            }
          },
          "overcurrent": false,
          "undervoltage": false,
          "lowPowerMode": false,
          "batteryChargeCategory": "N",
          "batteryHealth": "U",
          "inputPowerOn": true,
          "peripheralPowerOn": true,
          "recentComlosses": [],
          "unstableConnection": false,
          "syncStatus": {
            "synced": true,
            "details": {
              "timestamp": "2024-06-10T16:10:01.000Z"
            }
          }
        }
      ],
      "connectionStatus": {
        "connected": true,
        "details": {
          "timestamp": "2024-05-29T20:29:49.000Z"
        }
      },
      "syncStatus": {
        "synced": true,
        "details": {}
      },
      "softwareVersion": {
        "cnbackend": "2.1.1",
        "saserver": "2.1.4"
      },
      "macAddress": "b8:ff:aa:25:ff:ec",
      "ipv4Address": "10.45.87.45",
      "ipv6Address": "afef:a5bb:sefs:fsdf:ba27:ebff:fe25:fwef"
    }
  ],
  "killTimer": 259200
}

Introduction​

The system object​

Basic Endpoints​

Retrieve a system​

Request

Response

Update a system​

Request

Response

Create a system token​

Request

Response

Search a system​

Request

Response

Retrieve the status of a system​

Request

Response

Introduction

The system object

Basic Endpoints

Retrieve a system

Update a system

Create a system token

Search a system

Retrieve the status of a system