Auth Endpoints

Login

File: api/login.php Method: POST Auth: None (this creates the token)

Flow:

1. Looks up user by email where role=3 (student)
2. Handles temp_ prefixed passwords (temporary passwords strip the prefix before verification)
3. Verifies password with password_verify()
4. If status=1 (active), generates JWT and returns user data
5. US-specific: checks moderation ratings due, review periods
6. UK-specific: includes houseSearching field
7. Returns viewing rewards, house filters, housemate group size, roomie status

Response: 200 with JWT token, user profile, filters, viewing data. 401 for invalid password, 403 for blocked account, 404 for unknown email.

Signup

File: api/signup.php Method: POST Auth: None

Flow:

1. Validates all required fields (returns 422 for missing)
2. Checks for duplicate email (returns 409)
3. Uploads profile picture to S3 (or uses default)
4. Hashes password with password_hash(PASSWORD_DEFAULT)
5. Inserts user record
6. Handles referral code if provided
7. Sends welcome email via Mailgun
8. Handles bills signup code if provided
9. Processes pending friend invitations
10. Sends FCM notification to friend who invited the user
11. Returns JWT token

UK Signup

File: api/ukSignup.php Method: POST

UK-specific signup flow. To be documented further based on actual file content.

SSO Login (US)

File: api/sso_login.php Method: POST

Initiates SAML SSO flow via SimpleSAMLphp. Redirects to university Identity Provider. After callback, creates a temporary JWT containing SAML attributes.

SSO Auth (US)

File: api/sso_auth.php Method: POST Auth: Temporary JWT from SSO login

Flow:

1. Decodes temporary JWT to extract SAML attributes
2. Extracts collegeUID from SAML attribute urn:oid:1.3.6.1.4.1.9904.5.1.1.1.1
3. Looks up user by collegeUID in users table
4. If first activation (no last_seen), adds user to Mailchimp and HubSpot
5. Records user session
6. Returns full user profile with app JWT
7. Includes moderation data, review periods, viewing rewards, friend requests

SSO Dev Bypass

File: api/sso_auth_devbypass.php

Development-only SSO bypass for testing without university IdP.

Apple Sign-In

File: api/appleSignin.php Method: POST

Looks up user by appleID column. If found, returns existing user data with new JWT. If not found, creates new user account.

Google Sign-In

File: api/googleSignin.php Method: POST

Google OAuth verification using google/apiclient. Verifies the Google credential and looks up/creates user.

Facebook Sign-In

File: api/facebookSignin.php Method: POST

Facebook authentication flow.

Send OTP

File: api/send_otp.php Method: POST

Generates a 6-digit OTP, stores it in the users table, sends via Twilio SMS to the user’s registered phone number. Returns 200 on success, 404 if email not found.

Verify OTP

File: api/verify_otp.php Method: POST

Validates the OTP against the stored value and expiry.

Signup OTP

File: api/signUpOtp.php Method: POST

OTP flow during signup process.

Password Reset

File: api/forgot_password_reset.php Method: POST

File: api/password_reset.php Method: POST

Password reset flows.

Email Check

File: api/emailCheck.php Method: POST

Checks if an email exists in the system. Used during signup to detect duplicates early.

Check Existing User

File: api/checkExistingUser.php Method: POST

Checks if a user exists by various identifiers.