Roles API

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

A RolePermissions object looks like:

{
  // Whether the role has the permission
  "enabled": true,
  // Whether the permission is locked by this role
  "locked": false,
  // Whether the permission applies to the account this role is in. Only present if
  // enabled is true
  "applies_to_self": true,
  // Whether the permission cascades down to sub accounts of the account this role is
  // in. Only present if enabled is true
  "applies_to_descendants": false,
  // Whether the permission can be modified in this role (i.e. whether the permission
  // is locked by an upstream role).
  "readonly": false,
  // Whether the value of enabled is specified explicitly by this role, or inherited
  // from an upstream role.
  "explicit": true,
  // The value that would have been inherited from upstream if the role had not
  // explicitly set a value. Only present if explicit is true.
  "prior_default": false
}

A Role object looks like:

{
  // The label of the role.
  "label": "New Role",
  // The label of the role. (Deprecated alias for 'label')
  "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', 'inactive', or 'built_in'
  "workflow_state": "active",
  // A dictionary of permissions keyed by name (see permissions input parameter in
  // the 'Create a role' API).
  "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

Scope: url:GET|/api/v1/accounts/:account_id/roles

A paginated list of the roles available to an account.

Request Parameters:

Parameter Type Description

account_id

Required

string

Parameter		Type	Description
account_id	Required	string	The id of the account to retrieve roles for.
state[]		string	Filter by role state. If this argument is omitted, only 'active' roles are returned. Allowed values: `active`, `inactive`
show_inherited		boolean	If this argument is true, all roles inherited from parent accounts will be included.

The id of the account to retrieve roles for.

state[]

string

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

Allowed values: active, inactive

show_inherited

boolean

If this argument is true, all roles inherited from parent accounts will be included.

Returns a list of Roles

Get a single role RoleOverridesController#show

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

Scope: url:GET|/api/v1/accounts/:account_id/roles/:id

Retrieve information about a single role

Request Parameters:

Parameter		Type	Description
account_id	Required	string	The id of the account containing the role
role_id	Required	integer	The unique identifier for the role
role		string	The name for the role

Returns a Role

Create a new role RoleOverridesController#add_role

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

Scope: url:POST|/api/v1/accounts/:account_id/roles

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

Request Parameters:

Parameter		Type	Description
label	Required	string	Label for the role.
role		string	Deprecated alias for label.
base_role_type		string	Specifies the role type that will be used as a base for the permissions granted to this role. Defaults to 'AccountMembership' if absent Allowed values: `AccountMembership`, `StudentEnrollment`, `TeacherEnrollment`, `TaEnrollment`, `ObserverEnrollment`, `DesignerEnrollment`
permissions[<X>][explicit]		boolean	no description
permissions[<X>][enabled]		boolean	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 import_sis -- Import SIS data 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 -- 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 manage_feature_flags -- Enable or disable features at an account level [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 import_outcomes -- [ TaDo] Import outcome data 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 (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_announcements -- [STADO] View announcements read_question_banks -- [ TADo] View and link to question banks read_reports -- [ TAD ] 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 lti_add_edit -- [ TAD ] LTI add and edit read_email_addresses -- [sTAdo] See other users' primary email address view_user_logins -- [ TA ] View login ids for users 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]		boolean	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>.
permissions[<X>][applies_to_self]		boolean	If the value is 1, permission <X> applies to the account this role is in. The default value is 1. Must be true if applies_to_descendants is false. This value is only returned if enabled is true.
permissions[<X>][applies_to_descendants]		boolean	If the value is 1, permission <X> cascades down to sub accounts of the account this role is in. The default value is 1. Must be true if applies_to_self is false.This value is only returned if enabled is true.

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/roles.json' \
     -H "Authorization: Bearer <token>" \
     -F 'label=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/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/roles/:id

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:

Parameter		Type	Description
role_id	Required	integer	The unique identifier for the role
role		string	The name for the role

Returns a Role

Activate a role RoleOverridesController#activate_role

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

Scope: url:POST|/api/v1/accounts/:account_id/roles/:id/activate

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

Request Parameters:

Parameter		Type	Description
role_id	Required	integer	The unique identifier for the role
role		Deprecated	The name for the role

Returns a Role

Update a role RoleOverridesController#update

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

Scope: url:PUT|/api/v1/accounts/:account_id/roles/:id

Update permissions for an existing role.

Recognized roles are:

TeacherEnrollment
StudentEnrollment
TaEnrollment
ObserverEnrollment
DesignerEnrollment
AccountAdmin
Any previously created custom role

Request Parameters:

Parameter	Type	Description
label	string	The label for the role. Can only change the label of a custom role that belongs directly to the account.
permissions[<X>][explicit]	boolean	no description
permissions[<X>][enabled]	boolean	These arguments are described in the documentation for the add_role method.
permissions[<X>][applies_to_self]	boolean	If the value is 1, permission <X> applies to the account this role is in. The default value is 1. Must be true if applies_to_descendants is false. This value is only returned if enabled is true.
permissions[<X>][applies_to_descendants]	boolean	If the value is 1, permission <X> cascades down to sub accounts of the account this role is in. The default value is 1. Must be true if applies_to_self is false.This value is only returned if enabled is true.

Example Request:

curl https://<canvas>/api/v1/accounts/:account_id/roles/2 \
  -X PUT \
  -H 'Authorization: Bearer <access_token>' \
  -F 'label=New Role Name' \
  -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