# Canvas

> Sync sections, launch GroutCode from a module item, and post scores to Canvas assignments.

Canonical: https://grout.app/developer/documentation/guides/canvas/

## Roster sync

Scopes: `students:write`, `groups:write`.

1. `GET /api/v1/courses/:id/sections?include[]=students` on Canvas.
2. For each student without a Grout id, `POST /students` with `student_id` = Canvas `sis_user_id` and `personal_email` = Canvas login email; store the returned `id` and `login_email` as a custom user data entry.
3. One Grout group per Canvas section: `POST /groups` then `PATCH /groups/{id}` with the full `student_ids` each run.

## Launch from a module item

Scope: `sso:write`.

Create an **External URL** module item pointing at your service. The service mints a token (`POST /sso/tokens { email, app: "groutcode", redirect: "exam:<id>" }`) and redirects to `launch_url`. If you use LTI 1.3, do the same from your launch endpoint after validating the id token.

## Scores to Canvas

Scopes: `submissions:read`, `webhooks:write`.

Subscribe to `exam.graded`. Map each Grout `exam_id` to a Canvas assignment id, then:

```http
PUT /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id
Content-Type: application/json

{ "submission": { "posted_grade": "87" } }
```

Use `resubmission_required` to leave a comment instead of a grade. Canvas rate limits apply; batch updates with `POST …/submissions/update_grades` for large classes.

## Guardians

If parents use Canvas observer accounts, mirror them: `POST /guardians` per observer with `guardian_type: "guardian"` so they can also follow Alpha Learning reports at audit.grout.app.