How to get custom role - Curse context

Hi Team,

I am using the following Canvas API to fetch roles at both account and course levels:

https://mylearnerjourney.instructure.com/api/v1/accounts/1/roles?state[]=active&show_inherited=true&per_page=100

This API returns all default and custom roles at the account level, but for the course level, I only receive the default roles. I am filtering course roles using:

"is_account_role": false

However, this only returns default roles and does not include the custom roles created in the course context.

I also tried using the course enrollments API:

https://mylearnerjourney.instructure.com/api/v1/courses/116/enrollments

But this also does not return the custom course roles.

Could you please advise on how to fetch custom roles created specifically at the course level using the Canvas API?

Thanks in advance for your help.

Best regards,
Praveen Shukla

Find more posts tagged with

Developers

Accepted answers

All comments

jeremyfw

Hello Praveen,

Canvas does not actually have true course-level custom roles.

All custom roles are created at the account level. When you “create a role in a course,” Canvas is really creating an account-level role scoped to that course via permissions and enrollments not a new role object that lives only inside the course.

That design choice explains everything you’re seeing.

Why your current API calls behave the way they do

1. `GET /accounts/:account_id/roles`

This is the only endpoint that returns custom roles.

It returns:
- default roles (Teacher, Student, TA, etc.)
- all custom roles created in that account
It does not distinguish whether a role is used in a given course

This is expected behavior.

📘 Docs:
Roles API
https://canvas.instructure.com/doc/api/roles.html

2. Why you won’t ever find “course-only roles”

There is no API endpoint (and no internal object) for:

“roles created in this course”
“custom roles owned by a course”

Because they don’t exist as first-class entities.

Canvas stores:

roles → at the account
enrollments → at the course
the link between them happens at enrollment time

The correct way to infer “custom roles used in a course”

You have to join data from two APIs.

Step 1: Get all roles at the account level

GET /api/v1/accounts/:account_id/roles?state[]=active&show_inherited=true

This gives you every possible role, default and custom.

Step 2: Get enrollments for the course

GET /api/v1/courses/:course_id/enrollments

Each enrollment includes:

role
role_id
type

📘 Docs:
Enrollments API
https://canvas.instructure.com/doc/api/enrollments.html

Step 3: Match enrollments → roles

Now you can:

filter enrollments by role_id
look up that role_id in the roles list
determine:
- which custom roles are actually used in that course
- which users are assigned to them

This is the only reliable method.

Why `is_account_role: false` doesn’t help

That flag is misleading unless you already know Canvas’ internals.

is_account_role = false just means: “This role can be used at the course level”
It does not mean: “This role was created at the course level”

Every role usable in a course - default and custom will often return the same value here.

Where Canvas documents this (indirectly)

Canvas never states “course-level roles don’t exist” in one bold sentence, but it’s implied across the docs:

Roles API – roles are always account-scoped
https://canvas.instructure.com/doc/api/roles.html
Enrollments API – roles are applied via enrollments
https://canvas.instructure.com/doc/api/enrollments.html
Permissions model – permissions are attached to roles, not courses
https://community.canvaslms.com/t5/Admin-Guide/Permissions/ta-p/177

When you line those up, the architecture becomes clear.

test29

Thanks for your reply …

I was also looking for custom roles whose scope is course-level only.

test29

Hi @jeremyfw ,

Thank you for your detailed response. However, I am still looking for a way to retrieve all custom roles created in Canvas LMS, both at the account level and within the course context, as this is required for our LTI permission page.

Currently, I am unable to fetch any of the custom roles using the API.

I am using the following endpoint:

https://mylearnerjourney.instructure.com/api/v1/accounts/1/roles?state[]=active&show_inherited=true&perpage=100

But the response does not include all the roles that are visible in the UI (as shown in the screenshot). I also tried different account IDs, but the result remains the same.

Additionally, I tried fetching inactive roles:

https://mylearnerjourney.instructure.com/api/v1/accounts/1/roles?state[]=inactive&show_inherited=true&perpage=100

This returns only one role, whereas I have created nearly six custom roles in the system. That suggests the remaining roles are neither inactive nor being returned by the API.

Could you please advise how to properly retrieve all custom roles (account-level and course-level) via the Canvas API? is there any settings that I am missing while creating the roles?

Thank you for your support.

Best regards,
Praveen Shukla

Chris

Hi @test29,

Your API call looks pretty close to correct to me. Are you getting 10 responses, none of them being custom roles? I'm asking that because you do have one typo in your call, the "perpage" should actually be "per_page". Correcting that may help you get more results, but you really should also handle the api pagination in your code and not rely solely on the per_page parameter as that could change in the future.

If all roles are created at the root account level, you'd be all set with a single call to the root account. However, if you're doing this for an LTI other clients will be using, you can't guarantee where they'll be creating roles. In that case to get every possible role in the instance, you'd need to first list all accounts for the instance, then run the roles call for each subaccount and collect the results. Technically, with the show_inherited parameter being used, you could just do this call for subaccounts at the end of the tree (ones that have no other subaccounts).

Finally, if you want to ensure you get all accounts for the instance, you need to be using a token for a user that that has root level permission to access everything, standard users, students, and teachers will not be able to list accounts and access all of the roles.

I hope this helps!

-Chris

test29

thanks Chris it really help me . there was typo.

Unanswered Questions

Dropped Scores
I have Canvas set to drop the lowest quiz score, however, my students can only barely tell that the grade text is slightly grey when dropped. Can it have a tag like the "missing" and "exempt" ones in the student gradebook?
Batch edit assignment due dates by section
My Canvas shell has three different sections that all meet at different times throughout the week. I need to be able to batch edit assignment due dates by section, but right now Canvas can't filter by section for batch edit. My only option is now to manually (tediously) edit due dates for each assignment individually.
Change Group Assignments to NOT save if no groups are selected
Morning! One of the more frustrating aspects of Canvas are groups and the issues that show up when copying courses that have them. But now we have yet another issue. Most recently we have had instances where people mark an assignment/discussion as a group assignment but then do not link the discussion or assignment to any…
Has anyone experienced the "Empty Course" page for Speedgrader, when there actually are students assigned and active on the assignment?
So, we have encountered a few assignments where the Speedgrader presents the teacher with the "Empty Course" page, even though the course is not empty. I have discovered two New Quizzes in the same course where this has occurred, despite multiple students being assigned (at Module level, which passes the permission down to…
Problems with grading since update
A teacher has expressed concerns with the recent update. Exact concern is as follows: "My Canvas has been acting glitchy since the last "update." For instance, when I grade essays the highlight and cursor tools do not always work. I have to try highlighting several times,or come back later to finish. It's told me I "ran…