Multi-Role Authentication & Login

Purpose - Provides a single sign-in surface for four distinct audiences (DHE, School Admin, Employee, Student), on both web and mobile, using email or phone plus an OTP or password. 

Who Can Use It 

Anyone with an active account: DHE users, DHE Employees, School Admins, Employees, and Students. 

Key Capabilities 

• Initiate login by email or phone for a given user type (web or mobile flow).
• Verify a one-time password (OTP) to complete login. 
• Log in with password when a password has been set. 
• Resend OTP on the same session. 
• Automatic detection of "no password yet" users, who are asked to set a password using OTP. 
• Multi-school flow: if a School Admin's email or phone is linked to more than one school, the system returns the list of schools so the user can pick one before continuing.
• Multi-student flow: if a phone or email is shared across sibling students, the system returns the list of student accounts so the user can pick one. 
• Student-specific first-time login flow: a dedicated initiate and verify pair that lets a student set their contact details. 

How It Works 

• The user enters email or phone plus their user type on the login screen.
• The system checks the account: 

1. If multiple schools are linked to the login (School Admin), the list of schools is returned for the user to pick.
2. If multiple students are linked to the login, the list of students is returned.

• If no password is set, an OTP is sent and the user is prompted to create a password. 
• If a password is set, the user enters it; on success an OTP is sent to complete login. 
• The user submits the OTP, and on success an access token is issued. 

Rules & Restrictions 

• Email is compared in a case-insensitive way; leading and trailing spaces are trimmed.
• Deleted or archived accounts cannot log in; the response reads "unauthorized user, please contact administrator!". 
• For School Admin sign-in, the linked employee account must exist and be active. The school cannot be reached if the underlying employee is deleted or archived.
• Only schools whose registration is confirmed appear in the school picker after login.
• A signed session is bound to the account's current token version, so a forced logout invalidates old tokens.