Roles

Roles are a named set of permissions. These permissions can be given to Users and Groups within the context of a collection via Collection Memberships.

Note

The Roles API is currently in Beta. It can be considered reasonably stable for beginning development work, but as it is a work in progress, it may still have small breaking changes introduced without warning.

Note

The Roles API can currently only be used by Administrator users.

Permissions

Name Description
admin-panel-access Access the admin panel
collection-create Create collections
collection-delete Delete collections
collection-move Move collections
collection-read List and view collections
collection-share Share collections
collection-update Edit collections
comment-create Post comments
comment-delete Delete comments
comment-read View comments
comment-update Approve comments
media-create Create and upload media
media-delete Delete media
media-download Download media
media-like Like media
media-play Play media
media-publish Publish media
media-read List and view media
media-update Edit media

Permission Dependencies

Many permissions require the presence of other permissions. Attempting to add a permession without the permissions it relies upon will not add that permission. Removing a permission will remove all permissions that depend upon it. Note that permission dependencies are transitive, so for example adding the media-play permission requires adding both media-read and collection-read.

Name Depends Upon
admin-panel-access None
collection-create collection-read
collection-delete collection-read
collection-move collection-create, collection-delete, collection-update
collection-read None
collection-share collection-update
collection-update collection-read
comment-create comment-read
comment-delete comment-read
comment-read media-read
comment-update comment-read
media-create media-read
media-delete media-update
media-download media-read
media-like media-read
media-play media-read
media-publish media-create
media-read collection-read
media-update media-read, admin-panel-access

Listing Roles

GET /api2/roles

Fetch a list of roles.

Query Parameters:
 
  • display_name (optional) – Filter for roles by display name. It must be an exact match to be returned
  • deletable (optional) – Filter roles based on whether or not they can be deleted.
  • lti (optional) – Filter roles based on whether or not they are an LTI/LIS role.
  • permissions (optional) – A comma seperated list of permissions that the returned roles must have.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
Location: /api2/roles

{
  "items": [
    {
      "id": "2",
      "display_name": "Student",
      "created_on": "2012-11-09T12:02:47Z",
      "modified_on": "2013-01-18T02:38:48Z",
      "permissions": [
        "media-read",
        "media-play",
        "media-like",
        "comment-create",
        "collection-read"
      ],
      "deletable": true,
      "lti": false,
      "links": {
        "self": "/api2/roles/2"
      }
    },
    {
      "id": "3",
      "display_name": "Teacher",
      "created_on": "2012-11-09T12:02:47Z",
      "modified_on": "2013-01-18T02:38:48Z",
      "permissions": [
        "media-read",
        "media-create",
        "media-play",
        "media-like",
        "comment-create",
        "collection-read"
      ],
      "deletable": true,
      "lti": false,
      "links": {
        "self": "/api2/roles/3"
      }
    }
  ],
  "links" {
    "self": "/api2/roles"
  }
}
GET /api2/roles/count

Return a count of roles.

This endpoint accepts all the same filter parameters as GET /api2/roles.

Example Response:

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

{
   "count": 27
}

Fetching a Role

GET /api2/roles/(role_id)

Get a single role.

Example Response:

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

{
  "id": "2",
  "display_name": "Student",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "permissions": [
    "media-read",
    "media-play",
    "media-like",
    "comment-create",
    "collection-read"
  ],
  "deletable": true,
  "lti": false,
  "links": {
    "self": "/api2/roles/2"
  }
}

Creating a Role

POST /api2/roles

Add a new role.

Json Parameters:
 
  • display_name (required) – Sets the role’s display name.
  • permissions (required) – A JSON list of permission names that this role will have.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
Location: /api2/roles/4

{
  "id": "4",
  "display_name": "New Role",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "permissions": [
    "media-read",
    "media-play",
    "media-like",
    "comment-create",
    "collection-read"
  ],
  "deletable": true,
  "lti": false,
  "links": {
    "self": "/api2/roles/4"
  }
}

Updating a Role

POST /api2/roles/(role_id)

Update a role’s attributes.

Json Parameters:
 
  • display_name (optional) – Sets the role’s display name.
  • permissions (optional) – A JSON list of permission names that this role will have.
POST /api2/roles/(role_id)/add-permissions
Json Parameters:
 
  • permissions (required) – A JSON list of permission names to add to this group
POST /api2/roles/(role_id)/remove-permissions
Json Parameters:
 
  • permissions (required) – A JSON list of permission names to remove from this group

Deleting a Role

DELETE /api2/roles/(role_id)

Delete a role.

This endpoint is idempotent; attempting to delete a role that does not exist will return a successful response.

Example Response:

HTTP/1.1 204 No Content

Previous topic

Groups

Next topic

Thumbnails

This Page