Organizations

Introduction

Organizations are hierarchical containers of permissions. Parent organizations represent PDK dealers while child organizations represent their customers. You can learn more about the PDK topology here. Note that the API sometimes refers to organizations as OUs (organizational units).

info

The easiest way to distinguish between dealers and customers is to inspect the ancestors property. Dealers will only have one ancestor while customers will have two ancestors.

The organization object

{
  "id": "64398c446e22d40001eeaf34",
  "name": "Test Dealer",
  "useBluetoothCredentials": true,
  "useTouchMobileApp": true,
  "allowCredentialResets": true,
  "ancestors": ["544557759a01deb9874c02ef"],
  "parent": "544557759a01deb9874c02ef",
  "children": [
    {
      "id": "6512e8f4dd7de8191957fcc1",
      "name": "Test Customer",
      "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
      "useBluetoothCredentials": true,
      "useTouchMobileApp": true,
      "allowCredentialResets": true
    }
  ],
  "panels": [],
  "userPermissionLevel": "admin",
  "parentPermissionLevel": "guest",
  "permissions": [
    {
      "_id": "644a19ba6e22d40001eec733",
      "userId": "644a19ba6e22d40001eec732",
      "email": "john@example.com",
      "name": "John Wiegand",
      "role": "admin"
    }
  ]
}

Property	Type	Description
id	String	The organization ID.
name	String	The organization name.
systemId	String	The system ID. If a system ID is not present, then the organization represents either a dealer or a legacy customer.
useBluetoothCredentials	Boolean	Whether Bluetooth credentials are enabled for the organization.
useTouchMobileApp	Boolean	Whether mobile credentials are enabled for the organization.
allowCredentialResets	Boolean	Whether credential self-help is enabled for the organization.
ancestors	String[]	A list of parent organization IDs.
parent	String	The parent organization ID.
children	Object[]	A list of customers.
children.id	String	The customer organization ID.
children.name	String	The customer name.
children.systemId	String	The customer system ID. If a system ID is not present, the the organization represents a legacy customer.
children.useBluetoothCredentials	Boolean	Whether Bluetooth credentials are enabled for the customer.
children.useTouchMobileApp	Boolean	Whether mobile credentials are enabled for the customer.
children.allowCredentialResets	Boolean	Whether credential self-help is enabled for the customer.
panels	Object[]	A list of cloud nodes associated with the organization.
panels.uuid	String	The cloud node ID.
panels.name	String	The cloud node name.
panels.id	String	The cloud node serial number.
panels.registeredDate	String	An ISO 8601 timestamp representing the time at which the cloud node was registered.
panels.online	Boolean	Whether the cloud node is online.
userPermissionLevel	String	The authenticated user's permission level for the organization.
parentPermissionLevel	String	The authenticated user's permission level for the organization's parent.
permissions	Object[]	A list of permission objects associated with the organization.

Basic Endpoints

Retrieve an organization

Request

GET https://accounts.pdk.io/api/organizations/{{organization_id}} HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
organization_id	Path	String	Yes	The organization ID.
id_token	Header	String	Yes	A valid ID token.

Response

The response contains an organization object.

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

{
  "id": "64398c446e22d40001eeaf34",
  "name": "Test Dealer",
  "useBluetoothCredentials": true,
  "useTouchMobileApp": true,
  "allowCredentialResets": true,
  "ancestors": ["544557759a01deb9874c02ef"],
  "parent": "544557759a01deb9874c02ef",
  "children": [
    {
      "id": "6512e8f4dd7de8191957fcc1",
      "name": "Test Customer",
      "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
      "useBluetoothCredentials": true,
      "useTouchMobileApp": true,
      "allowCredentialResets": true
    }
  ],
  "panels": [],
  "userPermissionLevel": "admin",
  "parentPermissionLevel": "guest",
  "permissions": [
    {
      "_id": "644a19ba6e22d40001eec733",
      "userId": "644a19ba6e22d40001eec732",
      "email": "john@example.com",
      "name": "John Wiegand",
      "role": "admin"
    }
  ]
}

Search within an organization

This endpoint allows you to search for customers and cloud nodes within a specific organization. Searchable fields include organization names, cloud node names, and cloud node serial numbers.

Request

GET https://accounts.pdk.io/api/organizations/{{organization_id}}/search?q=test HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
organization_id	Path	String	Yes	The organization ID.
q	Query	String	No	The search query.
id_token	Header	String	Yes	A valid ID token.

Response

The response contains an array of entities matching the search query.

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

[
  {
    "_id": "6512e8f4dd7de8191957fcc1",
    "type": "ou",
    "name": "Test Customer",
    "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0"
  },
  {
    "_id": "1234ABC",
    "type": "panel",
    "name": "Test Cloud Node",
    "uuid": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
    "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0"
  }
]

Property	Type	Description
_id	String	The customer ID or cloud node serial number.
type	String	The entity type. Possible values include ou for customers and panel for cloud nodes.
name	String	The name of the customer or cloud node.
uuid	String	The cloud node ID.
systemId	String	The system ID.

List all my organizations

Request

GET https://accounts.pdk.io/api/organizations/mine HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid ID token.

Response

The response contains an array of organization objects.

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

[
  {
    "id": "64398c446e22d40001eeaf34",
    "name": "Test Dealer",
    "useBluetoothCredentials": true,
    "useTouchMobileApp": true,
    "allowCredentialResets": true,
    "ancestors": ["544557759a01deb9874c02ef"],
    "parent": "544557759a01deb9874c02ef",
    "children": [
      {
        "id": "6512e8f4dd7de8191957fcc1",
        "name": "Test Customer",
        "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
        "useBluetoothCredentials": true,
        "useTouchMobileApp": true,
        "allowCredentialResets": true
      }
    ],
    "panels": [],
    "userPermissionLevel": "admin",
    "parentPermissionLevel": "guest",
    "permissions": [
      {
        "_id": "644a19ba6e22d40001eec733",
        "userId": "644a19ba6e22d40001eec732",
        "email": "john@example.com",
        "name": "John Wiegand",
        "role": "admin"
      }
    ]
  },
  {
    "id": "6512e8f4dd7de8191957fcc1",
    "name": "Test Customer",
    "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
    "useBluetoothCredentials": true,
    "useTouchMobileApp": true,
    "allowCredentialResets": true,
    "ancestors": ["544557759a01deb9874c02ef"],
    "parent": "544557759a01deb9874c02ef",
    "children": [],
    "panels": [
      {
        "uuid": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
        "name": "Test Panel",
        "id": "1234ABC",
        "registeredDate": "2023-09-27T22:21:56.865Z",
        "online": true
      }
    ],
    "userPermissionLevel": "admin",
    "parentPermissionLevel": "guest",
    "permissions": []
  }
]

Search within all my organizations

This endpoint allows you to search for customers and cloud nodes within all your organizations. Searchable fields include organization names, cloud node names, and cloud node serial numbers.

Request

GET https://accounts.pdk.io/api/organizations/mine/search?q=test HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
q	Query	String	No	The search query.
id_token	Header	String	Yes	A valid ID token.

Response

The response contains an array of entities matching the search query.

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

[
  {
    "_id": "6512e8f4dd7de8191957fcc1",
    "type": "ou",
    "name": "Test Customer",
    "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0"
  },
  {
    "_id": "1234ABC",
    "type": "panel",
    "name": "Test Cloud Node",
    "uuid": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
    "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0"
  }
]

Property	Type	Description
_id	String	The customer ID or cloud node serial number.
type	String	The entity type. Possible values include ou for customers and panel for cloud nodes.
name	String	The name of the customer or cloud node.
uuid	String	The cloud node ID.
systemId	String	The system ID.

Customers

Create a customer

Creating a new customer will automatically create a corresponding system.

Request

POST https://accounts.pdk.io/api/organizations/{{dealer_id}}/children HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  "name": "Test Customer"
}

Parameter	Location	Type	Required	Description
dealer_id	Path	String	Yes	The organization ID of the dealer.
id_token	Header	String	Yes	A valid ID token.
name	Body	String	Yes	The customer name.
useBluetoothCredentials	Body	Boolean	No	Whether Bluetooth credentials should be enabled for the organization. The default is true.
useTouchMobileApp	Body	Boolean	No	Whether mobile credentials should be enabled for the organization. The default value is false.
allowCredentialResets	Body	Boolean	No	Whether credential self-help should be enabled for the organization. The default value is true.
type	Body	String	No	Which architecture should be used. Possible values include multi-site (default) for the 2.0 architecture and legacy for the 1.0 architecture. If omitted or set to multi-site, a system will automatically be created.

Response

The response contains the newly created organization object. Note that not all available properties are included in the response.

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

{
  "id": "64398c446e22d40001eeaf34",
  "name": "Test Customer",
  "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
  "allowCredentialResets": true,
  "children": [],
  "panels": [],
  "permissions": []
}

Retrieve a customer

Request

GET https://accounts.pdk.io/api/organizations/{{customer_id}} HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
customer_id	Path	String	Yes	The organization ID of the customer.
id_token	Header	String	Yes	A valid ID token.

Response

The response contains an organization object.

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

{
  "id": "6512e8f4dd7de8191957fcc1",
  "name": "Test Customer",
  "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
  "useBluetoothCredentials": true,
  "useTouchMobileApp": true,
  "allowCredentialResets": true,
  "ancestors": ["544557759a01deb9874c02ef"],
  "parent": "544557759a01deb9874c02ef",
  "children": [],
  "panels": [
    {
      "uuid": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
      "name": "Test Panel",
      "id": "1234ABC",
      "registeredDate": "2023-09-27T22:21:56.865Z",
      "online": true
    }
  ],
  "userPermissionLevel": "admin",
  "parentPermissionLevel": "guest",
  "permissions": []
}

Update a customer

Request

PUT https://accounts.pdk.io/api/organizations/{{dealer_id}}/children/{{customer_id}} HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  "name": "Test Customer"
}

Parameter	Location	Type	Required	Description
dealer_id	Path	String	Yes	The organization ID of the dealer.
customer_id	Path	String	Yes	The organization ID of the customer.
id_token	Header	String	Yes	A valid ID token.
name	Body	String	Yes	The customer name.
useBluetoothCredentials	Body	Boolean	No	Whether Bluetooth credentials should be enabled for the organization. The default is true.
useTouchMobileApp	Body	Boolean	No	Whether mobile credentials should be enabled for the organization. The default value is false.
allowCredentialResets	Body	Boolean	No	Whether credential self-help should be enabled for the organization. The default value is true.

Response

HTTP/1.1 204 No Content

Delete a customer

Request

DELETE https://accounts.pdk.io/api/organizations/{{dealer_id}}/children/{{customer_id}} HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
dealer_id	Path	Integer	Yes	The organization ID of the dealer.
customer_id	Path	Integer	Yes	The organization ID of the customer.
id_token	Header	String	Yes	A valid ID token.

Response

HTTP/1.1 204 No Content

List all customers

Request

GET https://accounts.pdk.io/api/organizations/{{dealer_id}}/children HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
dealer_id	Path	String	Yes	The organization ID of the dealer.
id_token	Header	String	Yes	A valid ID token.

Response

The response contains an array of organization objects.

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

[
  {
    "id": "6512e8f4dd7de8191957fcc1",
    "name": "Test Customer",
    "systemId": "b7e83c7d-2ff0-4b94-9275-08b31ee04fc0",
    "useBluetoothCredentials": true,
    "useTouchMobileApp": true,
    "allowCredentialResets": true,
    "ancestors": ["544557759a01deb9874c02ef"],
    "parent": "544557759a01deb9874c02ef",
    "children": [],
    "panels": [
      {
        "uuid": "7d829ff4-53e8-4d76-8762-1022ccdeae39",
        "name": "Test Panel",
        "id": "1234ABC",
        "registeredDate": "2023-09-27T22:21:56.865Z",
        "online": true
      }
    ],
    "userPermissionLevel": "admin",
    "parentPermissionLevel": "guest",
    "permissions": []
  }
]