Roles
Welcome to Our New API Docs! This is the new home for all things API (previously at Canvas LMS REST API Documentation).
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 'List assignable permissions'
// 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}}
}A Permission object looks like:
// A permission that can be granted to a role
{
// The API identifier for the permission
"key": "manage_lti_add",
// The human-readable label for the permission
"label": "LTI - add",
// The group this permission belongs to, if it is part of a granular permission
// group
"group": "manage_lti",
// The human-readable label for the group this permission belongs to
"group_label": "Manage LTI",
// The base role types this permission can be enabled for
"available_to": ["AccountAdmin", "AccountMembership", "TeacherEnrollment", "TaEnrollment", "DesignerEnrollment"],
// The base role types this permission is enabled for by default
"true_for": ["AccountAdmin", "TeacherEnrollment", "TaEnrollment", "DesignerEnrollment"]
}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:
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 Role objects.
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:
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 object.
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:
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> can be found on the Permissions list page.
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'Returns a Role object.
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:
role_id
Required integer
The unique identifier for the role
role
string
The name for the role
Returns a Role object.
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:
role_id
Required integer
The unique identifier for the role
role
Deprecated
The name for the role
Returns a Role object.
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:
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. The list of available permissions can be found on the Permissions list page.
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 object.
RoleOverridesController#manageable_permissions
GET /api/v1/accounts/:account_id/roles/permissions
Scope: url:GET|/api/v1/accounts/:account_id/roles/permissions
List all permissions that can be granted to roles in the given account.
This returns largely the same information documented on the Permissions list page, with a few caveats:
Permission labels and group labels returned by this API are localized (the same text visible in the web UI).
This API includes permissions added by plugins.
This API excludes permissions that are disabled in or otherwise do not apply to the given account.
Request Parameters:
search_term
string
If provided, return only permissions whose key, label, group, or group_label match the search string.
Returns a list of Permission objects.
This documentation is generated directly from the Canvas LMS source code, available on Github.
Last updated
Was this helpful?