Auth Flows

Authentication works differently across Housr systems. This page documents how each repo handles auth and how they interoperate.

Housr-App (Mobile)

The mobile app uses JWT-based authentication with tokens stored securely on-device.

Sign-in methods:

• Email + password
• Apple Sign-In (via expo-apple-authentication)
• Google Sign-In (via @react-native-google-signin/google-signin)

Token handling:

• Tokens are stored in secure storage (src/lib/token.ts)
• API v2 requests: Bearer JWT in the Authorization header
• API v1 requests: JWT sent as a form field (jwt) and as a plain Authorization header (not Bearer-prefixed)
• Token refresh is handled automatically by axios interceptors

Auth context:

• AuthProvider (src/context/auth-context.tsx) wraps the entire app
• Provides user, isAuthenticated, signIn, signOut, token
• All protected screens check auth state via this context

Housr-Webapp (Marketing Site)

The Webapp is mostly public-facing. It does not have user authentication on most pages.

How it authenticates with APIs:

• Server-side API calls use an API key (not user JWTs)
• Server Actions call the API on behalf of the user (e.g., enquiry forms, brochure requests)
• No session or token management on the client side for most flows

Exceptions:

• Bills checkout flow involves payment processing but uses server-side API calls, not client-side auth
• Perk partners payment flow uses Finix tokenization on the client

Housr Portal (Admin)

Portal uses standard Laravel session-based authentication.

How it works:

• Laravel’s built-in session auth with Filament’s authentication layer
• Users log in with email + password
• Sessions stored server-side (database or Redis)
• CSRF protection on all forms

Authorization:

• Usertype middleware controls access to different sections
• Role-based permissions via Filament’s authorization policies
• Different user types: admin, agent, landlord, etc.
• Each Filament resource defines its own access policies

API v1 (Legacy)

JWT authentication:

• Accepts JWT in the Authorization header (plain, not Bearer-prefixed)
• Also accepts JWT as a form field named jwt (for backwards compatibility)
• Tokens are generated on sign-in and returned to the client
• Token validation happens in middleware

API v2 (Current)

JWT authentication:

• Standard Bearer token in the Authorization header (Authorization: Bearer <token>)
• LegacyJwtGuard provides backwards compatibility with v1-style tokens
• Firebase JWT support for requests authenticated via Firebase Auth
• Module-specific middleware can add additional auth requirements

Auth guards:

• api — Standard Bearer JWT guard
• legacy-jwt — Accepts v1-style tokens for backwards compatibility
• firebase — Validates Firebase JWTs

Cross-System Auth Flow

A typical mobile app user session:

1. User signs in via the App (email/password or social auth)
2. API v1 or v2 validates credentials, returns a JWT
3. App stores the JWT securely
4. Subsequent requests include the JWT in headers (Bearer for v2, plain for v1)
5. If the token expires, the app refreshes it or prompts re-authentication

Portal users are completely separate — they authenticate directly with the Portal’s Laravel session system and never interact with the mobile APIs.