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 id of the role
"id": 1,
// 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",
// Whether this role applies to account memberships (i.e., not linked to an
// enrollment in a course).
"is_account_role": true,
// JSON representation of the account the role is defined 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",
// The date and time the role was created.
"created_at": "2020-12-01T16:20:00-06:00",
// The date and time the role was last updated.
"last_updated_at": "2023-10-31T23:59:00-06:00",
// 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
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: |
|
show_inherited | boolean |
If this argument is true, all roles inherited from parent accounts will be included. |
Get a single role RoleOverridesController#show
GET /api/v1/accounts/:account_id/roles/:id
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 |
Create a new role RoleOverridesController#add_role
POST /api/v1/accounts/:account_id/roles
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: |
|
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:
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. A comprehensive list of all permissions are available: Course Permissions PDF: bit.ly/cnvs-course-permissions Account Permissions PDF: bit.ly/cnvs-acct-permissions |
|
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'
Deactivate a role RoleOverridesController#remove_role
DELETE /api/v1/accounts/:account_id/roles/:id
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 |
Activate a role RoleOverridesController#activate_role
POST /api/v1/accounts/:account_id/roles/:id/activate
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 |
Update a role RoleOverridesController#update
PUT /api/v1/accounts/:account_id/roles/:id
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'