Zodiac Tech CRM Docs

Login & workspace selection

Sign in to the Android app with email or phone, password or one-time code — and how the app knows which workspace to open.

sales manager admin Easy ⏱ 5 min Updated 2026-10-06

Login & workspace selection

The Android app signs you into the same CRM account you use on the web. This page covers the four ways to log in, how the app finds your workspace, and the two demo options built into this build.

Who this is for

  • Sales agents signing in on their phone.
  • Admins helping a team member whose login is failing.

Difficulty: Easy · Time: about 5 minutes · Prerequisites: an account in the CRM (created in Team members) and, if OTP is used, a login method your workspace admin has enabled.

Step 1 — Check the server address

At the bottom of the login screen the app shows the CRM server it will contact (Server: …). Everything else depends on this:

  • If your business uses the operator's hosted CRM, the preconfigured address is already right.
  • If not, tap Advanced, enter the correct base URL, tap SAVE SERVER URL, and read the confirmation line. The URL must start with http:// or https:// and end with /.
  • For a server running on your own PC (local XAMPP), a phone on the same Wi-Fi must use the PC's LAN IP, for example: http://192.168.1.20/Lead%20Hub/api/v1/mobile/

What "workspace selection" means One CRM server can host many businesses (workspaces). The server address chooses the CRM install; your email/phone and password then sign you into the workspace your account belongs to. If you are not sure which server hosts your workspace, ask your admin — do not guess.

Step 2 — Choose how to sign in

The login screen has two switches: Email / Phone and Password / OTP Code. That gives four combinations:

Method How it works
Email + Password Your normal CRM password
Phone + Password Same password; phone must be on your CRM profile
Email OTP Tap SEND CODE, receive a one-time code by email, enter it
Phone OTP Code by SMS — either from your workspace's SMS provider, or via the workspace's Firebase project if it has one connected
  1. Select Email or Phone and type your details (phone numbers are entered as 10 digits with a +91 prefix).
  2. Select Password or OTP Code.
  3. For password: type it and tap SIGN IN.
  4. For OTP: tap SEND CODE, then enter the 6-digit code and tap VERIFY & SIGN IN.

Other useful behaviors:

  • Wait — what if I typed the wrong number? Tap Start over in the OTP panel to reset and try again.
  • A code that goes through Firebase may show "Waiting for Firebase verification…" while the app verifies automatically.
  • Whatever your workspace has not enabled surfaces as the server's clear error message — nothing is faked in the app.
  • You stay signed in on the device until you log out or the session expires (up to 90 days).

Demo build extras This build also has a TRY THE DEMO ACCOUNT button (signs into the seeded demo workspace — owner@abcrealty.demo) and a 🔍 EXPLORE DEMO — NO SERVER NEEDED button that opens the app offline with bundled sample data. Neither exists in a production build. See Demo APK (UI review).

Expected result

  • You land on Home, with today's follow-ups, assigned leads and the bottom tabs Home · Leads · Follow-ups · Calls · More.
  • If notifications are available, the app registers the device for push in the background — check More → Device health → Push notifications (FCM).
  • The device and its session appear in the CRM under Super Admin → Android App → Devices once it registers.

Common mistakes

Mistake What happens Fix
Using localhost on the phone Connection refused Use the PC's LAN IP (Step 1)
Forgetting the trailing / in the server URL "Invalid URL" when saving The app requires http(s)://…/
Typing the phone in international format Field expects 10 digits (+91 is shown) Enter 10 digits only
Five failed password attempts Login locked for 15 minutes Wait, or ask an admin to reset

Troubleshooting

  • "Invalid credentials" — after 5 failed attempts the account locks for 15 minutes; the API answers 429 ACCOUNT_LOCKED with a retry-time message until it expires. Wait, then retry with the correct password.
  • "This login method is not enabled" — the workspace admin must enable email/phone OTP for the workspace under the CRM's mobile login settings. See Mobile app setup.
  • Firebase OTP message about incomplete configuration — the workspace enabled Firebase OTP but its Firebase details are incomplete; ask the admin to check the CRM's Mobile App Login settings (see Push notifications for the same Firebase project).
  • No OTP email or SMS arrives — check spam, allow a minute, then resend. If SMS fails, your admin can verify the workspace SMS provider.
  • Login works on the web but not the app — check the server address first, then that the person has a CRM user account (not just a contact record).

Technical details

  • Mobile API endpoints: POST /api/v1/mobile/login, GET /api/v1/mobile/auth-config, POST /api/v1/mobile/otp/start, POST /api/v1/mobile/otp/verify (served by App\Http\Controllers\Api\Mobile\AuthController).
  • Login accepts email | phone plus password and a device_uuid; success issues a device token (Authorization: Bearer …) valid up to 90 days (TOKEN_TTL_DAYS = 90), resolved by the DeviceAuthenticate middleware against device_tokens.token_hash.
  • OTP codes are stored HMAC-SHA256-hashed with a random salt; attempts are capped (5 verify attempts) and issuance is rate-limited per identifier and per IP. Firebase phone OTP is verified server-side in AuthController::verify and SMS fallback uses the tenant's configured messaging provider.
  • Failed logins are recorded in login_attempts (LoginAttempt::recordFailureAndMaybeLock); panels enforce the 5-fails/15-minutes lockout through App\Filament\Auth\Pages\Login, and the mobile login endpoint applies the same lockout rule server-side.

Was this page helpful?