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/*)

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

3. Key Contracts

3.1 Customer registration

POST /api/mobile/auth/register

{
  "name": "Tenzin Sherpa",
  "email": "customer@example.com",
  "password": "StrongPass123!",
  "deviceInfo": {
    "deviceId": "android-abc",
    "deviceType": "android",
    "deviceName": "Pixel"
  }
}

Success creates a customer with emailVerified=false, sends the initial verification email, and returns only the user profile. No session tokens are issued until email verification or another trusted verification path succeeds.

Duplicate email responses:

The register endpoint does not automatically resend verification email on duplicate unverified accounts. Resend remains owned by the dedicated throttled resend endpoint.

3.2 Customer email login

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.3 Google one-time code exchange success shape (customer)

POST /api/mobile/auth/google/exchange

{
  "code": "e2f6d17ea01b5b824db6f7d8f936f1b5e97cef25afd8515b"
}

Response:

{
  "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. Set Password

Authenticated endpoints for setting or changing a user's password. Google-only users use this to create an EMAIL account with a password. Existing EMAIL users use this to change their password.

4.1 POST /api/auth/password/set

4.2 POST /api/mobile/auth/password/set

Set or change password for an authenticated user.

Authentication: JWT Bearer token

Rate limit: 5 requests per 15 minutes

Request body:

{
  "newPassword": "NewPass@1234",
  "currentPassword": "CurrentPass@123"
}

currentPassword is required only if the user already has a password.

Response (200 OK):

{
  "message": "Password set successfully.",
  "data": null,
  "errorCode": null
}

Errors:

• 400 Bad Request — currentPassword missing when user already has password
• 401 Unauthorized — Invalid JWT or incorrect currentPassword
• 429 Too Many Requests — Rate limit exceeded

5. hasPassword Field

All profile responses from:

• GET /api/auth/me
• GET /api/mobile/auth/me

include hasPassword: boolean.

• hasPassword: false means no EMAIL provider password exists yet.
• hasPassword: true means EMAIL provider password is set.

Frontend integration:

• hasPassword === false → show "Add Password"
• hasPassword === true → show "Change Password"

6. Google OAuth Behavior Matrix (Actual Runtime)

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

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.

The email/password registration path exposes AUTH_EMAIL_VERIFICATION_PENDING when the same unverified email attempts registration again. Clients should use the existing resend endpoint instead of retrying registration.

7. Operational Notes

Required Google env keys:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_CALLBACK_URL
• GOOGLE_OAUTH_REDIRECT_ALLOWLIST
• GOOGLE_OAUTH_STATE_SECRET
• GOOGLE_OAUTH_STATE_TTL_SECONDS (default 300)
• GOOGLE_OAUTH_CODE_TTL_SECONDS (default 90)

Callback URL must match mobile auth callback route:

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

Redirect allowlist must include exact frontend callback URLs, for example:

• https://app.thangka.navneetverma.com/auth/callback

8. 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*.
• Bearer tokens are never returned in browser redirect URLs.