Groups

Introduction

Groups allow users to apply shared rules to multiple people.

The group object

{
  "id": 1,
  "name": "Test Group",
  "partition": 0,
  "metadata": {}
}

Property	Type	Description
id	Integer	The group ID.
name	String	The group name.
partition	Integer	The partition ID.
metadata	Object	A user-defined metadata object.

Basic Endpoints

Create a group

Request

POST https://panel-{{panel_id}}.pdk.io/api/groups HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Group"
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
panel_token	Header	String	Yes	A valid panel token.
name	Body	String	Yes	The group name. This must be unique within a cloud node. The maximum length is 70 characters.
partition	Body	Integer	No	The partition ID. The default value is 0.
metadata	Body	Object	No	A user-defined metadata object. The data storage limit is 10 KB.

Response

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

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

{
  "id": 1
}

Retrieve a group

Request

GET https://panel-{{panel_id}}.pdk.io/api/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
group_id	Path	Integer	Yes	The group ID.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains a group object.

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

{
  "id": 1,
  "name": "Test Group",
  "partition": 0,
  "metadata": {}
}

Update a group

Request

PUT https://panel-{{panel_id}}.pdk.io/api/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Group",
  "partition": 0
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
group_id	Path	Integer	Yes	The group ID.
panel_token	Header	String	Yes	A valid panel token.
name	Body	String	Yes	The group name. This must be unique within a cloud node. The maximum length is 70 characters.
partition	Body	Integer	Yes	The partition ID.
metadata	Body	Object	No	A user-defined metadata object. The data storage limit is 10 KB.

Response

HTTP/1.1 204 No Content

Delete a group

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
group_id	Path	Integer	Yes	The group ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

List all groups

Request

GET https://panel-{{panel_id}}.pdk.io/api/groups HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
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.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains an array of group objects.

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

[
  {
    "id": 1,
    "name": "Test Group 1",
    "partition": 0,
    "metadata": {}
  },
  {
    "id": 2,
    "name": "Test Group 2",
    "partition": 0,
    "metadata": {}
  }
]

List a person's groups

Request

GET https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/groups HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	String	Yes	The person ID.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains an array of group objects.

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

[
  {
    "id": 1,
    "name": "Test Group 1",
    "partition": 0,
    "metadata": {}
  },
  {
    "id": 2,
    "name": "Test Group 2",
    "partition": 0,
    "metadata": {}
  }
]

Update a group's members

This endpoint will define all the members of a group. When adding or removing individual members, be sure to include the IDs of all other group members.

Request

PUT https://panel-{{panel_id}}.pdk.io/api/groups/{{group_id}}/persons HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "persons": [1, 2, 3]
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
group_id	Path	Integer	Yes	The group ID.
panel_token	Header	String	Yes	A valid panel token.
persons	Body	Integer[]	Yes	An array of person IDs.

Response

HTTP/1.1 204 No Content

Update a person's groups

This endpoint will define all the groups associated with a person. When adding or removing individual groups, be sure to include the IDs of all other groups.

Request

PUT https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/groups HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "groups": [1, 2, 3]
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The person ID.
panel_token	Header	String	Yes	A valid panel token.
groups	Body	Integer[]	Yes	An array of group IDs.

Response

HTTP/1.1 204 No Content

Remove a person from a group

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The person ID.
group_id	Path	Integer	Yes	The group ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content