Endpoint reference for admin auth and customer mobile auth, including Google OAuth customer flow and edge-case behavior.

Auth - API & Integration Guide

1. Route Surfaces

Auth is split across two surfaces:

Admin / backoffice auth: /api/auth/*
Customer mobile auth: /api/mobile/auth/*

Google OAuth is customer-only and is exposed only on /api/mobile/auth/*.

2. Endpoint Reference

2.1 Admin auth (`/api/auth/*`)

Method	Path	Auth	Description
POST	`/api/auth/login/email`	Public	Admin email/password login
POST	`/api/auth/password/forgot`	Public	Request password reset
POST	`/api/auth/password/reset`	Public	Reset password via token or OTP
POST	`/api/auth/email/verify/resend`	Public	Resend email verification
POST	`/api/auth/email/verify/confirm`	Public	Confirm email verification
POST	`/api/auth/refresh`	Public	Rotate refresh/access tokens
GET	`/api/auth/me`	JWT	Get current user profile
GET	`/api/auth/permissions`	JWT	Get current user permissions
POST	`/api/auth/phone/verify/request`	JWT	Send phone verification OTP
POST	`/api/auth/phone/verify/confirm`	JWT	Confirm phone verification OTP
DELETE	`/api/auth/logout`	JWT	Logout current session

2.2 Customer mobile auth (`/api/mobile/auth/*`)

Method	Path	Auth	Description
POST	`/api/mobile/auth/register`	Public	Customer register (email/password)
POST	`/api/mobile/auth/login/email`	Public	Customer email/password login
GET	`/api/mobile/auth/google`	Public	Start Google OAuth redirect
GET	`/api/mobile/auth/google/callback`	Public	Google callback; returns user + tokens
POST	`/api/mobile/auth/refresh`	Public	Rotate refresh/access tokens
POST	`/api/mobile/auth/password/forgot`	Public	Request password reset
POST	`/api/mobile/auth/password/reset`	Public	Reset password via token or OTP
POST	`/api/mobile/auth/email/verify/resend`	Public	Resend email verification
POST	`/api/mobile/auth/email/verify/confirm`	Public	Confirm email verification
GET	`/api/mobile/auth/me`	JWT	Get current user profile
DELETE	`/api/mobile/auth/logout`	JWT	Logout current session

3. Key Contracts

POST /api/mobile/auth/login/email

{
  "email": "customer@example.com",
  "password": "StrongPass123",
  "deviceInfo": {
    "deviceId": "android-abc",
    "deviceType": "android",
    "deviceName": "Pixel",
    "fcmToken": "optional-fcm-token"
  }
}

3.2 Google callback success shape (customer)

GET /api/mobile/auth/google/callback

{
  "message": "Google login successful.",
  "data": {
    "user": {
      "id": "uuidv7",
      "name": "Tenzin Sherpa",
      "email": "tenzin@example.com",
      "image": "https://lh3.googleusercontent.com/...",
      "emailVerified": true,
      "phone": null,
      "phoneVerified": false,
      "role": "customer"
    },
    "tokens": {
      "sessionId": "uuidv7",
      "accessToken": "<jwt>",
      "refreshToken": "<opaque-token>"
    }
  }
}

4. Google OAuth Behavior Matrix (Actual Runtime)

Google auth is handled by AuthService.handleGoogleOAuth() and has the following behavior:

Scenario	Result
Google profile has no email	`400 BadRequest` (`Google account must have an email.`)
Email belongs to admin account	`401 Unauthorized` (`Google login is not available for admin accounts.`)
Existing customer with Google account link	Updates provider tokens and logs in
Existing customer without Google account link	Creates `account` provider link and logs in
Existing customer with `emailVerified=false`	Marks `emailVerified=true`, then logs in
No existing customer	Auto-creates customer + Google account link, then logs in

Important note for pending email-verification users

If a customer registered via email/password but did not verify email yet, successful Google login with the same email will mark the customer as verified and issue tokens.

5. Operational Notes

Required Google env keys:

GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
GOOGLE_CALLBACK_URL

Callback URL must match mobile auth callback route:

Example: if PORT=5002, use http://localhost:5002/api/mobile/auth/google/callback

6. Guardrail Summary

Superadmin/admin login is email/password only.
Customer Google login/signup is mobile auth only.
There is no Google OAuth endpoint under /api/auth/google*.

Auth Module API & Integration Guide