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

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                      -- Users - act as
import_sis                       -- SIS Data - import
manage_account_memberships       -- Admins - add / remove
manage_account_settings          -- Account-level settings - manage
manage_alerts                    -- Global announcements - add / edit / delete
manage_catalog                   -- Catalog - manage
manage_courses                   -- Courses - add / edit / delete
manage_developer_keys            -- Developer keys - manage
manage_feature_flags             -- Feature Options - enable / disable
manage_global_outcomes           -- Manage learning outcomes
manage_jobs                      -- Manage background jobs
manage_master_courses            -- Blueprint Courses - add / edit / associate / delete
manage_role_overrides            -- Permissions - manage
manage_storage_quotas            -- Storage Quotas - manage
manage_sis                       -- SIS data - manage
manage_site_settings             -- Manage site-wide and plugin settings
manage_user_logins               -- Users - manage login details
manage_user_observers            -- Users - add / remove observers
read_course_content              -- Course Content - view
read_course_list                 -- Courses - view list
read_messages                    -- View notifications sent to users
reset_any_mfa                    -- Reset multi-factor authentication
site_admin                       -- Use the Site Admin section and admin all other accounts
view_course_changes              -- Courses - view change logs
view_error_reports               -- View error reports
view_feature_flags               -- Feature Options - view
view_grade_changes               -- Grades - view change logs
view_jobs                        -- View background jobs
view_notifications               -- Notifications - view
view_quiz_answer_audits          -- Quizzes - view submission log
view_statistics                  -- Statistics - view
undelete_courses                 -- Courses - undelete

[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 ] Course State - manage
create_collaborations            -- [STADo] Student Collaborations - create
create_conferences               -- [STADo] Web conferences - create
create_forum                     -- [STADo] Discussions - create
generate_observer_pairing_code   -- [ tado] Users - Generate observer pairing codes for students
import_outcomes                  -- [ TaDo] Learning Outcomes - import
lti_add_edit                     -- [ TAD ] LTI - add / edit / delete
manage_admin_users               -- [ Tad ] Users - add / remove teachers, course designers, or TAs in courses
manage_assignments               -- [ TADo] Assignments and Quizzes - add / edit / delete
manage_calendar                  -- [sTADo] Course Calendar - add / edit / delete events
manage_content                   -- [ TADo] Course Content - add / edit / delete
manage_files                     -- [ TADo] Course Files - add / edit / delete
manage_grades                    -- [ TA  ] Grades - edit
manage_groups                    -- [ TAD ] Groups - add / edit / delete
manage_interaction_alerts        -- [ Ta  ] Alerts - add / edit / delete
manage_outcomes                  -- [sTaDo] Learning Outcomes - add / edit / delete
manage_sections                  -- [ TaD ] Course Sections - add / edit / delete
manage_students                  -- [ TAD ] Users - add / remove students in courses
manage_user_notes                -- [ TA  ] Faculty Journal - manage entries
manage_rubrics                   -- [ TAD ] Rubrics - add / edit / delete
manage_wiki                      -- [ TADo] Pages - add / edit / delete
moderate_forum                   -- [sTADo] Discussions - moderate
post_to_forum                    -- [STADo] Discussions - post
read_announcements               -- [STADO] Announcements - view
read_email_addresses             -- [sTAdo] Users - view primary email address
read_forum                       -- [STADO] Discussions - view
read_question_banks              -- [ TADo] Question banks - view and link
read_reports                     -- [ TAD ] Courses - view usage reports
read_roster                      -- [STADo] Users - view list
read_sis                         -- [sTa  ] SIS Data - read
select_final_grade               -- [ TA  ] Grades - select final grade for moderation
send_messages                    -- [STADo] Conversations - send messages to individual course members
send_messages_all                -- [sTADo] Conversations - send messages to entire class
view_all_grades                  -- [ TAd ] Grades - view all grades
view_audit_trail                 -- [ t   ] Grades - view audit trail
view_group_pages                 -- [sTADo] Groups - view all student groups
view_user_logins                 -- [ TA  ] Users - view login IDs

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