Auth - API & Integration Guide

1. Route Surfaces

Auth is split across two surfaces:

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

Accounts are created by an administrator through the Users and Team modules. There is no self-service registration and no self-service account deletion. banned is the only account control.

2. Endpoint Reference

2.1 Admin auth (/api/auth/*)

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

3. Key Contracts

3.1 Customer email login

POST /api/mobile/auth/login/email

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

3.2 Password reset, and account invitations

POST /api/auth/password/reset and POST /api/mobile/auth/password/reset redeem an emailed credential and set a password. Send either token or otp, never neither:

token accepts either account-entry purpose — a password_reset or an account_invite. Somebody who has been sent a link cannot tell which of the two they hold, and both mean the same thing from their side: choose a password. An invitation is valid for 7 days; a reset for the OTP expiry, 15 minutes by default.

otp accepts password_reset only. Account invitations are redeemable by link only. The code is not printed in the invitation email, and the OTP lookup matches on purpose and person without a token hash to tell two live records apart — so accepting both purposes there could check a correct code against the wrong record, fail, and spend one of the five attempts that retire it.

Redeeming either credential retires the person's other account-entry credential, so an invitation and an administrator-issued reset cannot both stay usable once one of them has set a password.

Errors:

• 400 AUTH_PASSWORD_RESET_INPUT_REQUIRED — neither token nor otp was sent
• 400 AUTH_OTP_REQUIRED — the OTP branch was taken with no otp
• 400 AUTH_OTP_TARGET_REQUIRED — otp sent with neither email nor phone
• 400 AUTH_VERIFICATION_CODE_INVALID — the token or code is unknown, expired, already redeemed, or was retired by the person redeeming their other link. Ask for a fresh link rather than retrying this one.

Every successful reset notifies the account holder by email, including one they asked for themselves. That notification is the only signal a person gets that somebody else changed their password, so it is not suppressed for the expected case. Delivery failure never rolls back the password change.

4. Set Password

Authenticated endpoints for setting or changing a user's 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"