School and student workflows

This page explains how an outside integration fits around Handwrite's school app. These are signed-in app and staff workflows. The private /api/org/**, /api/auth/student/** and /api/internal/** handlers are not part of the supported public integration reference.

Ordinary classes and provisioned schools

Creating an ordinary kind: "class" organisation makes its human creator the owning teacher. A staff-provisioned school additionally has a School record, a school code and managed students in a separate sign-in pool. Buying a plan called school for an ordinary class does not by itself create that School record or student accounts.

Schools apply through support@handwrites.io or the school-setup contact topic. Authorised Handwrite staff approve the request. The approved school receives a code in the form HW-XXXX-XXXX; its admin is linked to an existing eligible verified customer account or receives a teacher invitation. The intended administrator accepts that invitation using their own customer account. The provision service itself does not send the approval email; the staff support workflow sends the reply.

Roster and temporary passwords

Teachers and co-teachers with members.manage use the Students tab at the school's signed-in management page. They add a student or preview/import a roster. Generic public membership creation does not create the associated student-pool account. Student deletion needs data.erase, held by teachers rather than co-teachers.

The current app supports CSV headers email,given_name,family_name with optional class, at most 200 rows and 1 MB per file. Preview validates before commit; a committed batch is all-or-nothing within that batch. A large school uses several separately reviewed files. Do not place roster data in URLs, error trackers or sample requests.

Temporary passwords are returned only to the authorised management action and are configured for seven days. The student changes the temporary password on first use. Cognito student creation suppresses provider email; the school distributes login instructions through its approved channel. A reset is another school management action, not an outside developer password API.

App-level add/import/reset actions implement idempotency for recovering their own response, including the temporary password. This does not mean every public /api/v1 write accepts an idempotency key. In particular, public managed-token issuance has no idempotency wrapper.

A student signs in on the Classroom host with school code or exact school name, school email and password. The backend checks active school, student record and student membership. Unknown school, incorrect credentials and disabled students intentionally receive the same sign-in failure behavior. Do not build an integration that probes this form to discover school codes or student membership.

The separate student-pool identity does not contain student email or display name; the app loads display information from the roster. School student accounts are distinct from customer accounts with the same address. Do not merge them by email or assume that the same address at two schools denotes one shared identity.

Students cannot use the customer purchase, developer-key or OAuth consent controls. School-wide suspension blocks the student app and initiates pool disable/sign-out work. A student's own disabled state remains separate when the school is resumed. Do not infer public API credential state from a successful or failed browser sign-in; API credentials also have their own policy, expiry and revocation checks.

Departure and closure

Remove a school student through the Students workflow so membership, student account and cloud-data cleanup remain coordinated. The generic public member removal route refuses school students. It is not a substitute for student account erasure.

School closure is a support/staff workflow, not DELETE /api/v1/orgs/{id}. It disables access and performs resumable cleanup; an accepted first step is not proof every student has been erased. An ordinary class owner can delete their own ordinary class through the public API. Your integration should disconnect and remove cached data according to the selected action rather than silently invoke deletion.

Verification boundary

These flows are checked against source. Student-pool configuration, Classroom-host deployment, mail delivery, external Voices authorizer support and a complete student login have not been verified by this documentation task. The 2026-10-26 provider snapshot found no Classroom portal DNS or CloudFront alias. Coordinate a disposable test school with the operator before live acceptance testing.

Ordinary classes and provisioned schools#

Roster and temporary passwords#

Student sign-in and boundaries#

Departure and closure#

Verification boundary#

Ordinary classes and provisioned schools

Roster and temporary passwords

Student sign-in and boundaries

Departure and closure

Verification boundary