Roles API

API for managing account- and course-level roles, and their associated permissions.

A Role object looks like:

{
  // The label and unique identifier of the role.
  "role": "New Role",

  // The role type that is being used as a base for this role.
  // For account-level roles, this is "AccountMembership".
  // For course-level roles, it is an enrollment type.
  "base_role_type": "AccountMembership"

  // JSON representation of the account the role is in.
  "account": {
    "id": 1019,
    "name": "CGNU",
    "parent_account_id": 73,
    "root_account_id": 1,
    "sis_account_id": "cgnu"
  },

  // The state of the role: "active" or "inactive"
  "workflow_state": "active",

  // A dictionary of permissions keyed by name (see permissions input
  // parameter in the "Create a role" API). The value for a given permission
  // is a dictionary of the following boolean flags:
  // - enabled:  Whether the role has the permission.
  // - locked: Whether the permission is locked by this role.
  // - readonly: Whether the permission can be modified in this role (i.e.
  //     whether the permission is locked by an upstream role).
  // - explicit: Whether the value of enabled is specified explicitly by
  //     this role, or inherited from an upstream role.
  // - prior_default: The value that would have been inherited from upstream
  //     if the role had not explicitly set a value. Only present if explicit
  //     is true.
  "permissions": {
    "read_course_content": {
      "enabled": true,
      "locked": false,
      "readonly": false,
      "explicit": true,
      "prior_default": false
    },
    "read_course_list": {
      "enabled": true,
      "locked": true,
      "readonly": true,
      "explicit": false
    },
    "read_question_banks": {
      "enabled": false,
      "locked": true,
      "readonly": false,
      "explicit": true,
      "prior_default": false
    },
    "read_reports": {
      "enabled": true,
      "locked": false,
      "readonly": false,
      "explicit": false
    },
    ...
  }
}

List roles RoleOverridesController#api_index

GET /api/v1/accounts/:account_id/roles

List the roles available to an account.

Request Parameters:

  • account_id

    The id of the account to retrieve roles for.

  • state[]

    Filter by role state. Accepted values are 'active' and 'inactive'. If this argument is omitted, only 'active' roles are returned.

Returns a list of Roles

Get a single role RoleOverridesController#show

GET /api/v1/accounts/:account_id/roles/:role

Retrieve information about a single role

Request Parameters:

  • account_id

    The id of the account containing the role

  • role

    The name and unique identifier for the role

Returns a Role

Create a new role RoleOverridesController#add_role

POST /api/v1/accounts/:account_id/roles

Create a new course-level or account-level role.

Request Parameters:

  • role

    Label and unique identifier for the role.

  • base_role_type
    Optional

    Accepted values are 'AccountMembership', 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', and 'DesignerEnrollment'

    Specifies the role type that will be used as a base for the permissions granted to this role.

    Defaults to 'AccountMembership' if absent

  • permissions[<X>][explicit]
    Optional
  • permissions[<X>][enabled]
    Optional

    If explicit is 1 and enabled is 1, permission <X> will be explicitly granted to this role. If explicit is 1 and enabled has any other value (typically 0), permission <X> will be explicitly denied to this role. If explicit is any other value (typically 0) or absent, or if enabled is absent, the value for permission <X> will be inherited from upstream. Ignored if permission <X> is locked upstream (in an ancestor account).

    May occur multiple times with unique values for <X>. Recognized permission names for <X> are:

    [For Account-Level Roles Only]
become_user                      -- Become other users
manage_account_memberships       -- Add/remove other admins for the account
manage_account_settings          -- Manage account-level settings
manage_alerts                    -- Manage global alerts
manage_courses                   -- Manage ( add / edit / delete ) courses
manage_developer_keys            -- Manage developer keys
manage_global_outcomes           -- Manage learning outcomes
manage_jobs                      -- Manage background jobs
manage_role_overrides            -- Manage permissions
manage_storage_quotas            -- Set storage quotas for courses, groups, and users
manage_sis                       -- Import and manage SIS data
manage_site_settings             -- Manage site-wide and plugin settings
manage_user_logins               -- Modify login details for users
read_course_content              -- View course content
read_course_list                 -- View the list of courses
read_messages                    -- View notifications sent to users
site_admin                       -- Use the Site Admin section and admin all other accounts
view_error_reports               -- View error reports
view_statistics                  -- View statistics

[For both Account-Level and Course-Level roles]
 Note: Applicable enrollment types for course-level roles are given in brackets:
       S = student, T = teacher, A = TA, D = designer, O = observer.
       Lower-case letters indicate permissions that are off by default.
       A missing letter indicates the permission cannot be enabled for the role
       or any derived custom roles.
change_course_state              -- [ TaD ] Change course state
comment_on_others_submissions    -- [sTAD ] View all students' submissions and make comments on them
create_collaborations            -- [STADo] Create student collaborations
create_conferences               -- [STADo] Create web conferences
manage_admin_users               -- [ Tad ] Add/remove other teachers, course designers or TAs to the course
manage_assignments               -- [ TADo] Manage (add / edit / delete) assignments and quizzes
manage_calendar                  -- [sTADo] Add, edit and delete events on the course calendar
manage_content                   -- [ TADo] Manage all other course content
manage_files                     -- [ TADo] Manage (add / edit / delete) course files
manage_grades                    -- [ TA  ] Edit grades
manage_groups                    -- [ TAD ] Manage (create / edit / delete) groups
manage_interaction_alerts        -- [ Ta  ] Manage alerts
manage_outcomes                  -- [sTaDo] Manage learning outcomes
manage_sections                  -- [ TaD ] Manage (create / edit / delete) course sections
manage_students                  -- [ TAD ] Add/remove students for the course
manage_user_notes                -- [ TA  ] Manage faculty journal entries
manage_rubrics                   -- [ TAD ] Edit assessing rubrics
manage_wiki                      -- [ TADo] Manage wiki (add / edit / delete pages)
read_forum                       -- [STADO] View discussions
moderate_forum                   -- [sTADo] Moderate discussions (delete/edit others' posts, lock topics)
post_to_forum                    -- [STADo] Post to discussions
read_question_banks              -- [ TADo] View and link to question banks
read_reports                     -- [sTAD ] View usage reports for the course
read_roster                      -- [STADo] See the list of users
read_sis                         -- [sTa  ] Read SIS data
send_messages                    -- [STADo] Send messages to individual course members
send_messages_all                -- [sTADo] Send messages to the entire class
view_all_grades                  -- [ TAd ] View all grades
view_group_pages                 -- [sTADo] View the group pages of all student groups

    Some of these permissions are applicable only for roles on the site admin account, on a root account, or for course-level roles with a particular base role type; if a specified permission is inapplicable, it will be ignored.

    Additional permissions may exist based on installed plugins.

  • permissions[<X>][locked]
    Optional

    If the value is 1, permission <X> will be locked downstream (new roles in subaccounts cannot override the setting). For any other value, permission <X> is left unlocked. Ignored if permission <X> is already locked upstream. May occur multiple times with unique values for <X>.

Example Request:

curl 'http://<canvas>/api/v1/accounts/<account_id>/roles.json' \ 
     -H "Authorization: Bearer <token>" \ 
     -F 'role=New Role' \ 
     -F 'permissions[read_course_content][explicit]=1' \ 
     -F 'permissions[read_course_content][enabled]=1' \ 
     -F 'permissions[read_course_list][locked]=1' \ 
     -F 'permissions[read_question_banks][explicit]=1' \ 
     -F 'permissions[read_question_banks][enabled]=0' \ 
     -F 'permissions[read_question_banks][locked]=1'
Returns a Role

Deactivate a role RoleOverridesController#remove_role

DELETE /api/v1/accounts/:account_id/roles/:role

Deactivates a custom role. This hides it in the user interface and prevents it from being assigned to new users. Existing users assigned to the role will continue to function with the same permissions they had previously. Built-in roles cannot be deactivated.

Request Parameters:

  • role

    Label and unique identifier for the role.

Returns a Role

Activate a role RoleOverridesController#activate_role

POST /api/v1/accounts/:account_id/roles/:role/activate

Re-activates an inactive role (allowing it to be assigned to new users)

Request Parameters:

  • role

    Label and unique identifier for the role.

Returns a Role

Update a role RoleOverridesController#update

PUT /api/v1/accounts/:account_id/roles/:role

Update permissions for an existing role.

Recognized roles are:

  • TeacherEnrollment

  • StudentEnrollment

  • TaEnrollment

  • ObserverEnrollment

  • DesignerEnrollment

  • AccountAdmin

  • Any previously created custom role

Request Parameters:

  • permissions[<X>][explicit]
    Optional
  • permissions[<X>][enabled]
    Optional

    These arguments are described in the documentation for the add_role method.

Example Request:

curl https://<canvas>/api/v1/accounts/:account_id/roles/TaEnrollment \ 
  -X PUT \ 
  -H 'Authorization: Bearer <access_token>' \ 
  -F 'permissions[manage_groups][explicit]=1' \ 
  -F 'permissions[manage_groups][enabled]=1' \ 
  -F 'permissions[manage_groups][locked]=1' \ 
  -F 'permissions[send_messages][explicit]=1' \ 
  -F 'permissions[send_messages][enabled]=0'
Returns a Role