Firebase phone OTP#

The Android app signs salespeople in with a workspace-discovered login screen. You choose which methods are offered: email + password, email OTP, phone + password, or phone OTP verified by Firebase. Firebase gives real phone-number verification without sending SMS from your own infrastructure — Meta-style phones are verified by Google's Identity Toolkit, and the CRM then matches the verified number to the right user.

Who this is for#

• Admin configuring their workspace's login methods (Settings → Connections → Mobile App).
• Super Admin setting platform defaults for all workspaces.
• Developer wiring a custom build or debugging the login flow.

Difficulty: Advanced · Time: about 20 minutes (plus ~5 minutes in the Firebase console) · Prerequisites:

• The Android app installed for at least one user (see Mobile app setup).
• A Google account to create a Firebase project.
• Optional: tenant SMTP configured for the email fallback (Email & SMTP).

Step 1 — Create the Firebase project#

1. Go to console.firebase.google.com and create a project (e.g. your-company-crm).
2. In Project settings → General → Your apps, click Add app → Android.
3. Register the app with package name com.zodiactech.crm (the app's application ID — it must match exactly; if you also install the demo-flavor APK, register com.zodiactech.crm.demo as a second app).
4. Add the SHA-1 of the signing keystore:
   • Debug builds: run gradlew signingReport in the Android project.
   • Release builds: add the SHA-1 of your release keystore.
   • Without the matching SHA-1, phone sign-in fails with an "app not authorized" error before any SMS is sent.
5. In Authentication → Sign-in method, enable the Phone provider.
6. In Project settings → General, copy the four values you need: Web API key, Project ID, Android App ID (looks like 1:123…:android:abc…) and Sender ID.

Step 2 — Turn on Firebase in the CRM#

As a client Admin: go to Settings → Connections → Mobile App — this is your workspace's override.

As a Super Admin: go to the platform's Mobile App Login — Platform Defaults page to set defaults every workspace inherits.

Fields:

Step 3 — Verify where settings apply#

Settings resolve in this order:

1. Workspace override (tenants.settings.mobile_auth) — set by the client Admin.
2. Platform defaults — set by the Super Admin.

At login the app calls GET /api/v1/mobile/auth-config and receives the platform-default method list plus the platform Firebase payload — it is deliberately platform-only, and a client-supplied workspace ID is never trusted. Workspace overrides resolve per-user at login and otp/*, once the account is known. Unconfigured Firebase simply disappears from the method list.

Step 4 — Test the login in the app#

1. Open the app and enter the phone number of a user in this workspace.
2. Choose Phone OTP → the app asks Firebase to send the code (SMS sent by Google, not the CRM).
3. Enter the code → the app returns the Firebase ID token to the CRM (POST /api/v1/mobile/otp/verify with the token).
4. The CRM verifies the token server-side against Google's Identity Toolkit (getAccountInfo), compares the verified phone number to the account, and only then mints a device token (90-day TTL, stored hashed).
5. Expected result: you land on the Home screen; the device appears under Android App → Devices in the Super Admin panel.

Email OTP and SMS fallback (no Firebase required)#

If you prefer not to use Firebase:

• Email OTP is generated by the CRM (HMAC-signed, single-use, TTL above) and mailed via your tenant SMTP — or the platform mailer as fallback.
• SMS OTP sends through your workspace's messaging provider — Twilio, Plivo or a custom provider, configured in messaging settings.

Rate limiting (applies to all OTP methods):

The limiter is checked before any work happens, so hammering the button does not cause sends or charges. Codes are single-use (burned before the session is minted), and request responses never echo the full phone/email — targets are masked.

Expected result#

The app's login screen offers the methods you enabled; with Firebase on, a phone number receives a real verification SMS from Google, and after verifying, the device is signed in and visible to the Super Admin — no google-services.json, no rebuild.

Common mistakes#

• Wrong Android package name in Firebase. It must be exactly the app's application ID — com.zodiactech.crm (demo flavor: com.zodiactech.crm.demo).
• Missing SHA-1 for the keystore you actually install with (debug vs release differ).
• Forgetting to enable the Phone provider under Authentication.
• Toggling Firebase on but leaving a field blank — the method stays off until all four values are present.
• Testing with a phone number that belongs to no CRM user — login is refused even if Firebase verified the number (the number must map to an active account in an active workspace).

Troubleshooting#

Technical details#

• Settings model: MobileAuthSettings (group mobile_auth), platform defaults + per-tenant override in tenants.settings.mobile_auth.
• Endpoints: GET /api/v1/mobile/auth-config, POST /api/v1/mobile/otp/start, POST /api/v1/mobile/otp/verify (accepts a CRM-issued code or a Firebase id_token), POST /api/v1/mobile/login (email/password + phone/password).
• Server-side Firebase verification: Google Identity Toolkit getAccountInfo with the resolved API key; the phone number returned by Google is compared to the account's PhoneNumber key.
• Codes: HMAC-SHA256 with a per-code salt, single-use, TTL from otp_ttl_minutes.
• Device tokens: hashed at rest (DeviceToken::hashToken), 90-day TTL, Authorization: Bearer for the mobile API.
• Pages: tenant MobileLoginSettingsPage (Settings → Connections → "Mobile App"); Super Admin MobileAuthSettingsPage ("Mobile App Login — Platform Defaults").

Related guides#

• How Firebase OTP works
• How mobile login finds your workspace
• Mobile app setup
• Mobile API (device tokens)
• Email & SMTP