Guardian portal setup

Provision parent portal accounts after enrollment, send welcome magic links, and fix the common reasons a guardian cannot sign in.

Students & families guide for day and boarding schools.

Last updated August 29, 2026

Two records sit behind every parent login. The Parent row holds the relationship to one student, plus contact and address details. The portal user is a separate account with the Parent role that can actually sign in. One portal user can be attached to several Parent rows, which is how a guardian with three children sees all three from a single login and a child switcher.

Admissions enrollment is the happy path: accepting an offer creates the guardian from the application, provisions the portal user, and sends a welcome magic link. Everything else - a second parent, a guardian who is not the applicant, a family added by import - is finished by office staff on /parents.

Prerequisites

SMTP configured, because both the welcome link and the self-service link are email-only. Test it at /settings/email-test
A Parent role exists in the roles table; without it the invite fails with a message telling you to run seeds
The guardian record carries an email address that no other user account already uses
The student is active on the roster, since portal screens scope to linked, active students

Magic-link behaviour

Link type	Validity	Triggered by
Self-requested sign-in link	15 minutes	Guardian asks for a link on the sign-in page
Welcome link	24 hours	Admissions enrollment or a portal invite from /parents

Handoff

The guardian link is what every family-facing screen scopes to. Fee balances, receipts, attendance, published grades, exam schedules, transport tracking, and leave requests all check for an active Parent row joining that user to that student. Link a guardian and the whole portal opens for that child; unlink and it closes, immediately and everywhere, without touching the student record itself.

Limits

Magic-link requests always report success, whether or not the address matches an account, so nobody can probe for valid parent emails
There is no SMS or WhatsApp sign-in link; email is the only passwordless channel
Unlinking a guardian removes portal visibility of that child but does not delete the account, so a parent of two children keeps access to the remaining one

Common questions

Quick answers in plain language.

A guardian record exists but the parent cannot sign in. What is missing?+

The Parent row has no linked portal user. Open /parents, find the guardian, and send a portal invite - POST /api/parents/[id]/portal-invite creates the account when missing and emails a welcome magic link. The guardian record must have an email address first.

How long is a magic link valid?+

A link the guardian requests themselves lasts 15 minutes. A welcome link sent by staff during enrollment or a portal invite lasts 24 hours. Requesting a new link deletes any earlier unused one for that account.

Why did enrollment create the guardian but not the portal login?+

The parent email already belongs to another user account. Enrollment falls back to creating the guardian record alone and reports that the portal must be linked manually. Give that guardian a distinct email, or link the existing account to the student at /parents.

Can a parent link themselves to a child?+

No. Only Platform Admin, Principal, Vice Principal, or Admin can create or link guardian records. There is no self-service claim flow, which is deliberate for child-data safety.