Partitions

Introduction

Partitions can be used to restrict the management of holders, groups, and rules within a system. These restrictions only apply to users with manager or reporter roles, while users with integrator or admin roles are able to manage entities across all partitions. Partitions might represent individual businesses within a multi-tenant commercial building, departments within a large company, or floors of a multi-story building.

The partition object

{
  "id": "619cceb0-ac58-4b15-a8ec-32efcb0476ba",
  "name": "Test Partition",
  "users": ["6d4b2edf5b38d7000169b240", "64529c8ba954b300028a64cf", "5da649b8c379b20001b2e4b5"],
  "default": true
}

Property	Type	Description
id	String	The partition ID.
name	String	The partition name.
users	String[]	An array of user IDs representing the pdk.io users assigned to manage this partition.
default	Boolean	Whether or not this is the default partition.

Basic Endpoints

Create a partition

Request

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

{
  "name": "Test Partition"
}

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 partition name. This must be unique within a system.
users	Body	String[]	No	An array of user IDs representing the pdk.io users assigned to manage this partition. User IDs can be obtained from the permissions endpoints.

Response

The response contains the ID of the newly created partition object.

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

{
  "id": "619cceb0-ac58-4b15-a8ec-32efcb0476ba"
}

Retrieve a partition

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

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

Response

The response contains a partition object.

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

{
  "id": "619cceb0-ac58-4b15-a8ec-32efcb0476ba",
  "name": "Test Partition",
  "users": [
    "6d4b2edf5b38d7000169b240",
    "64529c8ba954b300028a64cf",
    "5da649b8c379b20001b2e4b5"
  ],
  "default": true
}

Update a partition

Request

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

{
  "name": "Test Partition",
  "users": null
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
system_token	Header	String	Yes	A valid system token.
name	Body	String	Yes	The partition name. This must be unique within a system.
users	Body	String[]	Yes	An array of user IDs representing the pdk.io users assigned to manage this partition. User IDs can be obtained from the permissions endpoints.

Response

HTTP/1.1 204 No Content

Delete a partition

Request

DELETE https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

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

Response

HTTP/1.1 204 No Content

List all partitions

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

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
include	Query	String	No	A comma-delimited list of additional properties to include in the response. Available properties include attributes, devices, and users.
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 partition objects.

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

[
  {
    "id": "619cceb0-ac58-4b15-a8ec-32efcb0476ba",
    "name": "Default",
    "default": true
  },
  {
    "id": "0c5eeec2-e584-47b7-9c92-3c6879ead7fc",
    "name": "Test Partition"
  }
]

Update a partition's devices

This endpoint overwrites all the devices assigned to a partition. When adding or removing individual devices, be sure to include the IDs of all other devices.

Request

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

{
  "devices": [
    "11e21062-30fc-40f3-8309-7103c91d6c45",
    "99105ab2-0ae2-46ee-a410-3a201c75fa74",
    "19f664f2-b30a-4898-b4ce-207b05cd19b6"
  ]
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
system_token	Header	String	Yes	A valid system token.
devices	Body	String[]	Yes	An array of device IDs.

Response

HTTP/1.1 204 No Content

Remove a device from a partition

Request

DELETE https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/devices/{{device_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
device_id	Path	String	Yes	The device ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content