How mobile login finds your workspace#

The Android app never asks you for a workspace address or an ID. You sign in as you, and the server figures out which workspace you belong to, whether that workspace is in good standing, and issues your phone its own access token. This page traces that resolution — and why the app can never be pointed at the wrong workspace.

sequenceDiagram
    autonumber
    participant A as Android app
    participant C as CRM mobile API
    participant D as Database

    A->>C: GET /api/v1/mobile/auth-config
    C-->>A: Enabled sign-in methods for this install
    A->>C: POST /api/v1/mobile/login (email + password)<br/>or otp/start + otp/verify
    C->>D: Find the user
    C->>C: Resolve the user's OWN workspace (client-supplied tenant is never accepted)
    C->>C: Check method enabled + subscription active
    C->>D: issueDeviceToken → Device row + 64-char token (90-day TTL)
    C-->>A: Token + user/workspace payload
    A->>C: All later calls: Authorization: Bearer <token>

The trace in plain language#

1. The app asks what is allowed. GET /api/v1/mobile/auth-config returns which sign-in methods this installation/workspace enables — email+password, phone+password, email OTP, phone OTP — so the login screen only shows methods that can actually work.
2. You authenticate. Either:
   • Email + password via POST /api/v1/mobile/login, or
   • OTP via otp/start + otp/verify (How Firebase OTP works).
3. The workspace is resolved — server-side. The server looks up the found user's own workspace (users.tenant_id). A workspace id sent by the app is never accepted; there is no way to type your way into someone else's workspace.
4. Capability checks. If the method is disabled for that workspace, the API answers clearly: "Email sign-in is disabled for this workspace. Please use another sign-in method." (or the phone equivalent).
5. Subscription check. The workspace must be active — TenantSubscriptionState — or the API answers WORKSPACE_INACTIVE: "This workspace is not active. Renew the subscription to use the app."
6. Device token issued. issueDeviceToken() registers the phone (a Device row) and mints a 64-character token with a 90-day TTL. The app stores it securely.
7. Scoped calls. Every later request sends Authorization: Bearer <token>. The token identifies you, your workspace and this device — all data is scoped to the workspace automatically.

Troubleshooting notes#

Technical details#

• Controller: App\Http\Controllers\Api\Mobile\AuthController — login, auth-config, otp/start, otp/verify; responses include user + tenant + device payloads.
• Capability resolution: App\Services\MobileAuthConfigResolver (platform MobileAuthSettings, group mobile_auth; tenant override tenants.settings.mobile_auth) — flags email_password_enabled, phone_password_enabled, email_otp_enabled, phone_otp_enabled.
• Workspace isolation: resolution is always user → user's own tenant; NO_WORKSPACE error for accounts without one.
• Device tokens: 64-char tokens with 90-day TTL, stored on devices; revoked/expired tokens are rejected by the mobile API middleware. One device row per phone; signing in again mints a new token.
• The app also calls GET /api/v1/mobile/me to display current user + workspace + device state.

Related guides#

• Login & workspace selection · Mobile API (device tokens) · API authentication
• How Firebase OTP works · Permissions
• Cannot log in · Mobile not syncing / push not arriving