Organizations

Introduction

Organizations are hierarchical groups of cloud nodes and permissions. Parent organizations represent registered PDK dealers and child organizations represent their customers. Note that the API sometimes refers to organizations as OUs (organizational units).

The organization object

{
  "id": "64398c446e22d40001eeaf34",
  "name": "Test Dealer",
  "useBluetoothCredentials": true,
  "useTouchMobileApp": true,
  "allowCredentialResets": true,
  "ancestors": ["544557759a01deb9874c02ef"],
  "parent": "544557759a01deb9874c02ef",
  "children": [
    {
      "id": "643f0e8f6e22d40001eeb5e6",
      "name": "Test Customer",
      "useBluetoothCredentials": true,
      "useTouchMobileApp": true,
      "allowCredentialResets": true
    }
  ],
  "panels": [
    {
      "id": "1234ABC",
      "name": "Test Panel",
      "online": true,
      "allowCredentialResets": true,
      "credentialResetsPerMonth": 1,
      "reportBillingPolicy": "basic",
      "uri": "https://panel-1234ABC.pdk.io/",
      "registeredDate": "2023-05-01T14:42:36.220Z"
    }
  ],
  "readers": [
    {
      "_id": "032500000001773C",
      "deviceId": 1,
      "type": "red",
      "panelId": "1234ABC"
    }
  ],
  "userPermissionLevel": "admin",
  "parentPermissionLevel": "guest",
  "permissions": [
    {
      "userId": "644a19ba6e22d40001eec732",
      "_id": "644a19ba6e22d40001eec733",
      "email": "john@example.com",
      "name": "John Wiegand",
      "role": "admin"
    }
  ]
}

Property	Type	Description
id	String	The organization ID.
name	String	The organization name.
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 child organization objects. Note that not all available properties are included in each object.
panels	Object[]	A list of panel objects representing the cloud nodes associated with the organization.
readers	Object[]	A list of readers associated with the organization.
readers._id	String	The reader serial number.
readers.deviceId	Integer	The ID of the device associated with the reader.
readers.type	String	The reader type.
readers.panelId	String	The serial number of the cloud node associated with the reader.
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/ous/{{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": "643f0e8f6e22d40001eeb5e6",
      "name": "Test Customer",
      "useBluetoothCredentials": true,
      "useTouchMobileApp": true,
      "allowCredentialResets": true
    }
  ],
  "panels": [
    {
      "id": "1234ABC",
      "name": "Test Panel",
      "online": true,
      "allowCredentialResets": true,
      "credentialResetsPerMonth": 1,
      "reportBillingPolicy": "basic",
      "uri": "https://panel-1234ABC.pdk.io/",
      "registeredDate": "2023-05-01T14:42:36.220Z"
    }
  ],
  "readers": [
    {
      "_id": "032500000001773C",
      "deviceId": 1,
      "type": "red",
      "panelId": "1234ABC"
    }
  ],
  "userPermissionLevel": "admin",
  "parentPermissionLevel": "guest",
  "permissions": [
    {
      "userId": "644a19ba6e22d40001eec732",
      "_id": "644a19ba6e22d40001eec733",
      "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/ous/{{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": "649d9ca6e5adcb0001f2678f",
    "type": "ou",
    "name": "Test Customer"
  },
  {
    "_id": "1234ABC",
    "type": "panel",
    "name": "Test Panel"
  }
]

Property	Type	Description
_id	String	The ID of the customer or cloud node.
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.

List all my organizations

Request

GET https://accounts.pdk.io/api/ous/mine HTTP/1.1
Authorization: Bearer {{id_token}}
Accept: application/vnd.pdk.v2+json

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

info

This endpoint is versioned and requires the Accept header to work properly.

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": "643f0e8f6e22d40001eeb5e6",
        "name": "Test Customer",
        "useBluetoothCredentials": true,
        "useTouchMobileApp": true,
        "allowCredentialResets": true
      }
    ],
    "panels": [
      {
        "id": "1234ABC",
        "name": "Test Panel",
        "online": true,
        "allowCredentialResets": true,
        "credentialResetsPerMonth": 1,
        "reportBillingPolicy": "basic",
        "uri": "https://panel-1234ABC.pdk.io/",
        "registeredDate": "2023-05-01T14:42:36.220Z"
      }
    ],
    "readers": [
      {
        "_id": "032500000001773C",
        "deviceId": 1,
        "type": "red",
        "panelId": "1234ABC"
      }
    ],
    "userPermissionLevel": "admin",
    "parentPermissionLevel": "guest",
    "permissions": [
      {
        "userId": "644a19ba6e22d40001eec732",
        "_id": "644a19ba6e22d40001eec733",
        "email": "john@example.com",
        "name": "John Wiegand",
        "role": "admin"
      }
    ]
  },
  {
    "id": "64398c446e22d40001eeaf34",
    "name": "Test Customer",
    "useBluetoothCredentials": true,
    "useTouchMobileApp": true,
    "allowCredentialResets": true,
    "ancestors": ["544557759a01deb9874c02ef", "55ca2050bbed06f4348b26e8"],
    "parent": "55ca2050bbed06f4348b26e8",
    "children": [],
    "panels": [
      {
        "id": "1234DEF",
        "name": "Test Panel",
        "online": true,
        "allowCredentialResets": true,
        "credentialResetsPerMonth": 1,
        "reportBillingPolicy": "basic",
        "uri": "https://panel-1234DEF.pdk.io/",
        "registeredDate": "2023-05-01T14:42:36.220Z"
      }
    ],
    "readers": [
      {
        "_id": "032500000001773C",
        "deviceId": 1,
        "type": "red",
        "panelId": "1234DEF"
      }
    ],
    "userPermissionLevel": "admin",
    "parentPermissionLevel": "guest",
    "permissions": [
      {
        "userId": "644a19ba6e22d40001eec732",
        "_id": "644a19ba6e22d40001eec733",
        "email": "john@example.com",
        "name": "John Wiegand",
        "role": "admin"
      }
    ]
  }
]

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/ous/mine/search?q=test HTTP/1.1
Authorization: Bearer {{id_token}}
Accept: application/vnd.pdk.v2+json

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

info

This endpoint is versioned and requires the Accept header to work properly.

Response

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

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

[
  {
    "_id": "649d9ca6e5adcb0001f2678f",
    "type": "ou",
    "name": "Test Customer"
  },
  {
    "_id": "1234ABC",
    "type": "panel",
    "name": "Test Panel"
  }
]

Property	Type	Description
_id	String	The ID of the customer or cloud node.
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.

Customers

Create a customer

Request

POST https://accounts.pdk.io/api/ous/{{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.

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",
  "allowCredentialResets": true,
  "children": [],
  "panels": [],
  "readers": [],
  "permissions": []
}

Retrieve a customer

Request

GET https://accounts.pdk.io/api/ous/{{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": "64398c446e22d40001eeaf34",
  "name": "Test Customer",
  "useBluetoothCredentials": true,
  "useTouchMobileApp": true,
  "allowCredentialResets": true,
  "ancestors": ["544557759a01deb9874c02ef", "55ca2050bbed06f4348b26e8"],
  "parent": "55ca2050bbed06f4348b26e8",
  "panels": [
    {
      "id": "1234DEF",
      "name": "Test Panel",
      "online": true,
      "allowCredentialResets": true,
      "credentialResetsPerMonth": 1,
      "reportBillingPolicy": "basic",
      "uri": "https://panel-1234DEF.pdk.io/",
      "registeredDate": "2023-05-01T14:42:36.220Z"
    }
  ],
  "readers": [
    {
      "_id": "032500000001773C",
      "deviceId": 1,
      "type": "red",
      "panelId": "1234DEF"
    }
  ],
  "userPermissionLevel": "admin",
  "parentPermissionLevel": "guest",
  "permissions": [
    {
      "userId": "644a19ba6e22d40001eec732",
      "_id": "644a19ba6e22d40001eec733",
      "email": "john@example.com",
      "name": "John Wiegand",
      "role": "admin"
    }
  ]
}

Update a customer

Request

PUT https://accounts.pdk.io/api/ous/{{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/ous/{{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/ous/{{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": "64398c446e22d40001eeaf34",
    "name": "Test Customer",
    "useBluetoothCredentials": true,
    "useTouchMobileApp": true,
    "allowCredentialResets": true,
    "ancestors": ["544557759a01deb9874c02ef", "55ca2050bbed06f4348b26e8"],
    "parent": "55ca2050bbed06f4348b26e8",
    "children": [],
    "panels": [
      {
        "id": "1234DEF",
        "name": "Test Panel",
        "online": true,
        "allowCredentialResets": true,
        "credentialResetsPerMonth": 1,
        "reportBillingPolicy": "basic",
        "uri": "https://panel-1234DEF.pdk.io/",
        "registeredDate": "2023-05-01T14:42:36.220Z"
      }
    ],
    "readers": [
      {
        "_id": "032500000001773C",
        "deviceId": 1,
        "type": "red",
        "panelId": "1234DEF"
      }
    ],
    "userPermissionLevel": "admin",
    "parentPermissionLevel": "guest",
    "permissions": [
      {
        "userId": "644a19ba6e22d40001eec732",
        "_id": "644a19ba6e22d40001eec733",
        "email": "john@example.com",
        "name": "John Wiegand",
        "role": "admin"
      }
    ]
  }
]