Access Approvals

Schoolence protects school data through a membership approval layer. An account alone does not grant access — users must have an active school membership approved by an authorised school authority before they can see or interact with real school records.

Why approval is required

School data — student records, attendance, grades, financial information, behavioural logs, and staff details — is sensitive and must be protected under privacy and data-protection standards.

• Registration proves: this person can log in
• It does not prove: this person belongs to a school, holds a role, or is authorised to access student data
• Schoolence separates account identity from school authority to enforce least-privilege access

The three-layer model

UserAccount
  ↓
SchoolMembership
  ↓
Role + Status + School Scope

1. UserAccount — email, password, email verification status, global account state
2. SchoolMembership — links a user to a specific school with a role and approval status
3. Role + Scope — determines what actions and data are accessible within that school

Access to real school data requires all three layers to be in place and the membership to be ACTIVE.

Membership statuses

Status	Meaning
PENDING_EMAIL_VERIFICATION	Account created, email not yet confirmed
PENDING_SCHOOL_APPROVAL	Email verified, school membership requested but not yet approved
ACTIVE	Fully approved — real school data is accessible
SUSPENDED	Temporarily blocked (disciplinary, security, or administrative)
REJECTED	Membership request denied
REMOVED	Membership ended (user left school, role changed, etc.)

The key status for new registrations is PENDING_SCHOOL_APPROVAL.

Approval flow

User registers
  ↓
Email verified
  ↓
User selects school or enters school invitation code
  ↓
Membership created as PENDING_SCHOOL_APPROVAL
  ↓
Principal or authorised administrator reviews the request
  ↓
Membership becomes ACTIVE
  ↓
Real school data APIs unlock

What pending users see

Users with PENDING_SCHOOL_APPROVAL memberships can:

• Log into their dashboard shell
• See the sidebar menu and navigation
• View onboarding guides and help pages
• See a status banner: "Your access is waiting for school approval"
• Interact with demo/sandbox data (if enabled)

They cannot:

• Retrieve any real school data (students, classes, attendance, finances, etc.)
• Create, edit, or delete any school records
• Access role-specific features like grading, attendance-taking, or announcements

API calls for real school data return 403 Forbidden for unapproved users. The backend enforces deny-by-default — hiding frontend pages is secondary.

Role-specific approval rules

Each school role has a designated approver:

Role	Who can approve	Self-registration allowed?
Principal	Platform superadmin / manual school onboarding	Limited — first principal requires platform verification
Vice-principal	Principal	Yes
Administrator	Principal	Yes
Accountant	Principal	Yes
Teacher	Principal, Vice-principal, or Administrator	Yes
Student	Teacher or School Admin	Yes (with class code)
Parent	Self-managed (links to student)	Yes

First principal verification

A principal cannot self-approve. The first principal of a school must be verified through one of:

• Schoolence superadmin creates the school and assigns the principal
• Manual school onboarding — the school submits a verified request
• Official email domain — the school's domain is verified by the platform

Once the first principal is active, they can approve all other school members.

Teacher invitations

Teachers invited by a principal or administrator receive an invitation code. When they register with that code, their membership is automatically ACTIVE — no additional approval step is needed. This is the fastest path for bulk teacher onboarding.

Backend security

All API routes and server actions enforce these checks for every request:

1. Is the user authenticated? — valid session/token required
2. Is the email verified? — unverified emails cannot access school data
3. Does the user have an ACTIVE membership for this school? — membership.status === "ACTIVE"
4. Does the role allow this action? — role-based access control per endpoint
5. Is the requested data scoped to the same school? — schoolId from the membership, never from the frontend request
6. For teacher data, is the teacher assigned to this class/student? — row-level ownership check

The backend never trusts schoolId from the client. Every database query is scoped by the authenticated user's active membership schoolId.

Audit logging

Every approval action is recorded:

• Who approved (approver ID)
• Who was approved (member ID)
• Which school
• Which role
• Previous status → new status
• Timestamp

This audit trail supports privacy incident investigation and compliance reporting.

Workflow approvals

In addition to access approvals, Schoolence supports operational workflow approvals for multi-step school processes:

• Field trip requests
• Budget approvals
• Curriculum changes
• Disciplinary actions

These workflow approvals use a separate system with configurable approval chains (e.g., Teacher → Vice Principal → Accountant → Principal). See the school admin documentation for configuration details.