Roles and access control

The role names that actually exist, how a role name plus user type and context decides access, and where the page layer is stricter than the API.

Platform & access guide for day and boarding schools.

Last updated August 29, 2026

Access in Schoolyi is decided by a small set of named roles, read as strings in code, combined with the account's user type and a few contextual facts about the person - whether they are a class teacher, whether they have subject assignments, which committees they sit on. Capability paths such as modules.resources.library.view are computed from those inputs on each request and used to filter navigation and page controls.

There is no editable permission matrix. A permissions field exists on the role record and is displayed on /roles/[id], but no access check reads it, and that detail page is read-only. Creating a role with a new name therefore grants nothing at all, and renaming a seeded role removes the capabilities its holders had. Change who holds a role rather than trying to redefine one.

The roles that ship

Role	Scope
Platform Admin	Everything, and the only role that may use /users, /roles, /academic-system, /academic-year, /settings/seed and the school selector
Principal	Whole-school oversight: rosters, committees, calendar operations, every committee workspace
Vice Principal	Treated as identical to Principal by every leadership check in the codebase
Teacher	Assigned classes and subjects, and the only role eligible to chair a committee
Support Staff - Finance, IT, Lab Assistant, Purchasing, Facilities	Their own module, plus calendar events and terms
Transport	Driver duty: pickup, drop and boarding confirmation
Boarding Head, Warden, House Parent, Nurse, Security Officer, Designated Safeguarding Lead	Residential operations, each scoped to its part of the boarding module
Student	The learner portals - /student-dashboard, /my-class and the other /my- routes
Parent	/parent-dashboard and the linked children only
Vendor	The vendor portal
User	A holding role with no module access, used for accounts awaiting a decision

What narrows access beyond the role

User type - student, parent and vendor accounts are refused school operations regardless of role.
Staff type - PRT, TGT, PGT, Librarian and similar values decide library management and committee chair eligibility.
Class teacher fields on the class record, which is what grants the attendance register rather than any subject assignment.
Teacher assignments for the active year, which decide grade entry, timetable visibility and exam marking tasks.
Committee membership, which widens exam and admissions access without changing the base role.

Request flow

Where to manage access

/roles - the list of roles, with create, rename and deactivate. Platform Admin only.
/roles/[id] - a read-only detail view showing the description, how many users hold the role, and the stored permissions field.
/users and /users/[id] - assign a role, deactivate an account, resend verification.
/committees - membership, which is the intended way to grant temporary exam or admissions duty.
/classes - class teacher and co-class teacher, which is what grants attendance marking.

Common questions

Quick answers in plain language.

Can I edit what a role is allowed to do?+

No. Access is decided by the role name in code, and the permissions field stored on the role record is never read by an access check. /roles/[id] shows it but cannot change it. To give someone more access, move them to a different role, add them to a committee, or set the class teacher or teacher assignment that scopes the module in question.

What is the difference between the Principal and Vice Principal roles?+

Nothing, in access terms. Every leadership check in the codebase treats the two as interchangeable, so a Vice Principal has the same reach as a Principal across rosters, committees, calendar operations and reporting. The distinction is organisational, not technical.

Why can a Teacher chair a committee when a Principal cannot?+

Chair eligibility deliberately targets teaching staff: the account must be active, have the staff user type, hold the Teacher role exactly, and carry a teaching staff type such as PRT, TGT or PGT. Leadership already has full access to every committee workspace without being chair, so the chair slot is reserved for the teacher actually running the group.

Does hiding a menu item stop someone calling the endpoint?+

Not always. Most routes re-check the role, but some authorise only a valid session - the question bank and inventory movement endpoints and several calendar configuration endpoints among them. If a restriction matters for compliance, verify it in the route handler rather than assuming the hidden control is the whole control.