The Watershed Permission API is used by activity providers to permit access to data about a group of people to a person or group. This guide outlines the functional components of the API and provides an example.
As permissions are applied to people and groups, the Permission API builds on the concepts of the People API and the Groups API. Make sure you are familiar with those APIs before working with Permissions. You will need to have people and groups in place before assigning permissions.
Please note: This guide is designed to compliment a conversation with us. If you're looking to implement the Permission API and need assistance, please let us know and we will be glad to help.
Concepts
Permissions
Today, permissions control who can see data about a group of people. Permissions can be assigned to individual people or groups of people. In future, permissions may be used to restrict and allow other actions.
Permissions apply to everybody inside the group that the permission is applied to, including any sub groups. Where a permission is applied to a group or person directly (rather than to a group the person or group belongs to) that permission can be described as targeting the group or person.
API
This section outlines the allowed resources and methods of the Permissions API. In order to interact with the Permissions API, you will need authentication credentials and an organization id (org id).
Read Permissions for a Person
This request gets a list of all permissions that affect the person including permissions applied directly to that person and those applied to groups the person belongs to.
Request URL: /api/organizations/[org-id]/people/[person-id]/permissions
Method: GET
Expected response code: 200 OK
Response
A successful request will return an array of permission objects that affect the person.
Read Permissions Targeting a Person
This request gets a list of all permissions that directly target the person, including only permissions applied directly to that person and not those applied to groups the person belongs to.
Request URL: /api/organizations/[org-id]/people/[person-id]/targeting-permissions
Method: GET
Expected response code: 200 OK
Response
A successful request will return an array of permission objects that affect the person.
Read Permissions for a Group
This request gets a list of all permissions that affect the group including permissions applied directly to that group and those applied to groups the group belongs to.
Request URL: /api/organizations/[org-id]/groups/[group-id]/permissions
Method: GET
Expected response code: 200 OK
Response
A successful request will return an array of permission objects specifically applied to the group.
Read Permissions Targeting a Group
This request gets a list of all permissions that directly target the group, including only permissions applied directly to that person and not those applied to groups the group belongs to.
Request URL: /api/organizations/[org-id]/groups/[group-id]/targeting-permissions
Method: GET
Expected response code: 200 OK
Response
A successful request will return an array of permission objects specifically applied to the group.
Get all permissions
Request URL: /api/organizations/[org-id]/group-permissions
Method: GET
Expected response code: 200 OK
Response
A successful request will return a Collection object containing an array of permission objects; count contains the length of that array.
Get a Permission by Id
Request URL: /api/organizations/[org-id]/group-permissions/[permission-id]
Method: GET
Expected response code: 200 OK
Response
A successful request will return a single permission object.
Create a permission
Request URL: /api/organizations/[org-id]/group-permissions/
Method: POST
Expected response code: 200 OK
Request Content
A JSON encoded Permission object without id and created properties. The objects contained in the target, group and person properties do not need to be fully populated; only the id property is required for each.
Please note: Please note: permissions can apply either to a group or a person, not both. That means a permission object can have a group property or a person property but not both. To apply the same permissions to a person and a group (or to multiple people and groups) create multiple permissions.
Response
A successful request will return a complete permission object with all fields fully populated.
Edit a permission
Request URL: /api/organizations/[org-id]/group-permissions/[permission-id]
Method: PUT
Expected response code: 204 No Content
Request Content
A JSON encoded Permission object with updated values. The target, person and group properties cannot be changed and must match the existing permission. Delete and recreate the permission if these need to be changed.
Response
No content.
Delete a permission
Request URL: /api/organizations/[org-id]/group-permissions/[permission-id]
Method: DELETE
Expected response code: 200 OK
Response
The complete permission object that was deleted.
Entity Model
This section outlines the objects used in interacting with the Permissions API.
Permission
An object representing a particular permission. Each permission defines that one group or person is able to see data about a particular group.
|
Property |
Type |
Description |
|
id |
Integer |
Watershed’s id for the permission. Do not include this property when creating permissions. |
|
created |
ISO 8601 timestamp |
When the permission was created. Do not include this property when creating permissions. |
|
target |
Group |
The group whose data the permission relates to. See the Groups API documentation for details of the structure of this object. When creating and editing permissions, only the id property of the target group is required. |
|
person |
Person |
The person who should be able to see data about the target group. See the People API documentation for details of the structure of this object. Permissions include either a person or group property, not both. |
|
group |
Group |
The group who should be able to see data about the target group. See the Groups API documentation for details of the structure of this object. Permissions include either a person or group property, not both. |
Example
Below are some API interactions corresponding to an example scenario in which some personas are associated as people. In our example scenario, our organization has two learners, Bob and Sue. Bob belongs to the sales team and Sue belongs to the learning team. The learning team needs to be able to see data about the sales teams learning experiences.
First, let’s check if the organization has any permissions already set up:
GET /api/organizations/1234/group-permissions
This returns
200 OK
{
"count": 0,
"results": []
}
So, no permissions are set up. Let’s create a permission to give the learning team (id 2) access to data belonging to the sales team (id 1).
{
"target": {"id": 1},
"group": {"id": 2},
"childDepth": -1,
"individualAccess": false,
"global": false
}
This returns the complete permissions object with an id of 1.
Oops! We should have set the individualAccess property to true. Let’s fix that.
PUT /api/organizations/1234/group-permissions/1
Ok, now let’s check the permissions that apply to the learning team and to Sue (id 2). The permission applies directly to the learning team and indirectly to Sue. This means that the permission will not be returned if we query for permissions directly applied to Sue.
GET /api/organizations/1234/people/2/targeting-permissions
Because the permission is directly applied to the learning team and indirectly applied to Sue, the following calls will all return a result containing the permission we created.
GET /api/organizations/1234/people/2/permissions
GET /api/organizations/1234/groups/2/permissions
GET /api/organizations/1234/groups/2/targeting-permissions
We can also fetch the permission directly by id:
GET /api/organizations/1234/group-permissions/1
Later, policy changes and the learning team are no longer allowed to see the sales team’s data.
DELETE /api/organizations/1234/group-permissions/1
Great! You can now use the Permissions API to manage who can see data about which groups.