Permission API

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 APIand 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 People API for your activity provider and need assistance, please let us know and we will be glad to help.

This guide consists of 4 sections:

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

Details

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.

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.