Permissions

Introduction

Permissions provide the authorization needed for users to manage systems within an organization. In this context, users are pdk.io users (including integration clients), not credential holders within the access control system.

The permission object

{
  "_id": "64ac91ad6538760001e2d61c",
  "userId": "644a19ba6e22d40001eec732",
  "name": "John Wiegand",
  "email": "john@example.com",
  "role": "admin"
}

Property	Type	Description
_id	String	The permission ID.
userId	String	The user ID.
name	String	The user's name.
email	String	The user's email address.
role	String	The user's role. Possible values include reporter, manager, admin, and integrator. See the permissions table for details.

Basic Endpoints

Create a permission

Request

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

{
  "email": "john@example.com",
  "role": "admin"
}

Parameter	Location	Type	Required	Description
organization_id	Path	String	Yes	The organization ID.
id_token	Header	String	Yes	A valid ID token.
email	Body	String	Yes	The user's email address. A notification will be sent to this address.
role	Body	String	Yes	The user's role. Possible values include reporter, manager, admin, and integrator. See the permissions table for details.

Response

The response contains the newly created permission object. Note that the userId and name fields will not be set if the user has not yet created an account.

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

{
  "_id": "64ac91ad6538760001e2d61c",
  "userId": null,
  "name": "(Invitation Pending)",
  "email": "john@example.com",
  "role": "admin"
}

Update a permission

PUT https://accounts.pdk.io/api/organizations/{{organization_id}}/permissions/{{permission_id}} HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  "role": "admin"
}

Parameter	Location	Type	Required	Description
organization_id	Path	String	Yes	The organization ID.
permission_id	Path	String	Yes	The permission ID.
id_token	Header	String	Yes	A valid ID token.
role	Body	String	Yes	The user's updated role. Possible values include reporter, manager, admin, and integrator. See the permissions table for details.

Response

The response contains the updated permission object.

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

{
  "_id": "64ac91ad6538760001e2d61c",
  "userId": "644a19ba6e22d40001eec732",
  "name": "John Wiegand",
  "email": "john@example.com",
  "role": "admin"
}

Delete a permission

Request

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

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

Response

HTTP/1.1 204 No Content

List all permissions

Request

GET https://accounts.pdk.io/api/organizations/{{organization_id}}/ancestorPermissions 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 array of permission objects.

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

[
  {
    "_id": "5d3b22265b39d6000169b53b",
    "userId": "6d4b2edf5b38d7000169b240",
    "name": "John Wiegand",
    "email": "john@example.com"
  },
  {
    "_id": "64a874c148d66600043701aa",
    "userId": "64529c8ba954b300028a64cf",
    "name": "James Maxwell",
    "email": "james@example.com"
  },
  {
    "_id": "5f8a1685c13140000158b5de",
    "userId": "5da649b8c379b20001b2e4b5",
    "name": "Michael Faraday",
    "email": "michael@example.com"
  }
]