How Firebase OTP works#

Signing in to the mobile app with a phone number does not go through the CRM's own SMS stack by default — it goes through Firebase Phone Authentication. Firebase proves the person owns the number; the CRM then verifies that proof server-side and issues the device its own token. Here is the full loop, including the SMS fallback for workspaces that prefer their own provider.

The loop in plain language#

1. The app asks the CRM which sign-in methods this workspace allows.
2. The person chooses phone sign-in and enters their number.
3. Firebase sends the OTP by SMS; the person types the code.
4. Firebase hands the app a signed proof (an ID token) that the number was verified.
5. The app gives that proof to the CRM. The server verifies it against Google's servers — the app cannot fake it.
6. The CRM checks the person belongs to an active workspace, then issues a device token and registers the phone.
7. Every later API call uses that device token.

sequenceDiagram
    autonumber
    participant A as Android app
    participant C as CRM mobile API
    participant F as Firebase Auth
    participant G as Google Identity Toolkit

    A->>C: GET /api/v1/mobile/auth-config
    C-->>A: Enabled sign-in methods
    A->>F: Phone sign-in (runtime Firebase init)
    F->>A: SMS OTP
    A->>F: OTP entered
    F-->>A: Firebase ID token (proof)
    A->>C: POST /api/v1/mobile/otp/verify (token)
    C->>G: getAccountInfo — verify the token server-side
    G-->>C: Verified phone number
    C->>C: Resolve workspace, check subscription active
    C-->>A: Device token (64 chars, 90-day TTL)

The technical trace#

1. Auth config. GET /api/v1/mobile/auth-config resolves capabilities through MobileAuthConfigResolver: platform defaults from the MobileAuthSettings panel (settings group mobile_auth), overridden per tenant by tenants.settings.mobile_auth. Flags: email_password_enabled, phone_password_enabled, email_otp_enabled, phone_otp_enabled. The app renders only the methods enabled for this workspace.
2. OTP start. POST /api/v1/mobile/otp/start with the identifier:
   • Email OTP — the server generates the code and mails it through the tenant's SMTP configuration.
   • Phone OTP — either Firebase sends the SMS client-side (Firebase phone sign-in), or the workspace's SMS provider (tenant messaging settings) delivers a server-side code. If neither is configured, the API answers otp_unavailable: "Phone OTP is not configured for this workspace."
3. Limits. Starts are capped at 3 per identifier and 10 per IP per 10 minutes; verification allows 5 attempts. Rate-limit responses are deliberate safety, not errors.
4. Verification. POST /api/v1/mobile/otp/verify. For Firebase, the server validates the app-provided ID token against Google's Identity Toolkit getAccountInfo endpoint — no Admin SDK, no google-services.json (the Android app initialises Firebase at runtime from fetched config). For SMS/email codes, the server checks its own stored code.
5. Workspace resolution. The user's own workspace is used — a client-supplied tenant id is never accepted. Super-admin-only accounts with no workspace are rejected (NO_WORKSPACE).
6. Subscription gate. TenantSubscriptionState must be active or the API answers WORKSPACE_INACTIVE: "This workspace is not active. Renew the subscription to use the app."
7. Device token issued. issueDeviceToken() creates a Device row and mints a 64-character device token with a 90-day TTL. The app stores it and sends it as Authorization: Bearer … on every subsequent mobile API call.

Troubleshooting notes#

Related guides#

• Firebase phone OTP · Authentication · Mobile API (device tokens)
• How mobile login finds your workspace · Login & workspace selection
• Email or OTP not received